Trace Spec To Plan

---
name: trace-spec-to-plan
description:
  "Use before converting a plan into epics/beads/worktrees, and whenever you
  need to know whether a plan actually implements its spec. Walks EVERY
  requirement in the spec forward into the plan, one item at a time, and reports
  PLANNED / NAME-ONLY / ABSENT / PARTIAL. Distinct from verify-against-source,
  which reads the ARTIFACT and asks 'does this honor its source' — this reads
  the SPEC and asks 'where did this land'. Triggers - about to run
  project-setup, about to create epics or beads, plan review, 'does the plan
  cover the spec', 'did we miss anything', 'is the plan complete'."
# source: claude-plugin/skills/trace-spec-to-plan/SKILL.md
---

## Trace Spec → Plan

**Announce at start:** "I'm using trace-spec-to-plan to walk every spec
requirement into the plan."

### Why this exists

> 🔑 **A reviewer reading an artifact cannot see what isn't in it.**

That sentence is the whole justification. Every other review in the pipeline
reads the **plan** and asks _"is this sound?"_ — so it can only find defects in
what is present. **Absence has nothing to look at.**

⇒ **This replaces ad-hoc extra audits in the standard flow rather than
supplementing them.**

### When it runs

**Immediately before `project-setup` creates epics and beads.** That is the last
moment the spec is still in the room. Once a requirement is missing from the
plan **and** absent from the beads, the beads become the working set, nobody
consults the spec again, and the gap stops being discoverable at all.

Also valid: any time someone asks whether a plan is complete against its source.

#### Two hard preconditions

🚫 **NEVER run by the plan's own author.** Self-review cannot catch a
requirement the author never perceived — same person, same anchoring, same blind
spot. **Dispatch it.**

⚠️ **Run against a FROZEN plan.** A sweep racing live edits produces stale
findings that cost more to triage than they are worth.

### Sizing — the judgment call

1. **COUNT THE SPEC ITEMS FIRST, NOT PAGES.** Include every sub-item:
   `A3.1–3.4`, `P1–P8`, each ruled-out branch, each contradiction disposition,
   each named sequencing constraint. A spec that reads as "20-something
   sections" was **~65 discrete requirements**.
2. **≤ ~15 items ⇒ one agent. More ⇒ partition at ~12–15 items per agent.**
3. 🔴 **PARTITION BY SPEC ITEM, NEVER BY PLAN SECTION.** Section-partitioning
   manufactures false ABSENTs whenever a requirement is covered in a phase that
   auditor wasn't given. **Every agent searches the WHOLE plan for its own
   items.**
4. Write the shared instructions to **one file**
   (`resources/sweep-agent-prompt.md`) and give each agent only its item list.
   Keeps dispatches short and identical.
5. Use `efficient-multi-agent-research` for launch-and-wait mechanics.

### The four verdicts

| Verdict       | Means                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| **PLANNED**   | A task exists with concrete steps that would make the requirement true — files named, code or commands shown. |
| **NAME-ONLY** | The plan mentions, quotes, or asserts the requirement — but no task carries out steps.                        |
| **ABSENT**    | Not mentioned anywhere.                                                                                       |
| **PARTIAL**   | Part is planned; a named part is not. Say which.                                                              |

🔑 **NAME-ONLY IS THE LOAD-BEARING VERDICT AND THE ONE AN AGENT WILL AVOID
ASSIGNING.** It feels harsh against well-written prose, and PLANNED is always
the cheaper answer. **A requirement restated in a warning box, a doc comment, an
architecture paragraph, or a Definition-of-Done row is NAME-ONLY unless a task
carries out steps.**

#### Worked example — the judgement that decides this skill's value

```go
// assess computes one agent's verdict from the joined snapshot. It decides
// from PROCESS EVIDENCE — PID pair union session presence — and never from a
// self-written timestamp. It writes nothing.
func assess(s *Snapshot, j *Joined, agentID string) Verdict
```

A correct doc comment restating the spec, a precise signature, and it is
**consumed by a task elsewhere in the plan**. It reads as covered.

**Verdict: NAME-ONLY.** There is no body and no task anywhere implements one.
That function _was_ the reconciler. **The tell is not the quality of the prose —
it is that no step produces the thing.**

### Three questions per requirement

1. **Is there a task?** Naming a mechanism is not doing it.
2. 🔴 **Does the plan contain every step to make it true — INCLUDING CREATING
   SUBSTRATE THAT DOES NOT EXIST YET?** Open the real struct / table / interface
   at the plan's authored-against SHA. **A mechanism operating on a substrate
   that cannot hold the data is a silent no-op.** _Highest-yield question here:_
   a paired-write primitive was fully and correctly specified while the struct
   lacked the field and the table lacked the column.
3. **Would anything FAIL if it regressed?** A property with an implementation
   but no failing test is not achieved. **A manual grep in a Definition of Done
   cannot fail next month.**

### Framing — do not get this backwards

🔴 **A gap is a MISSING STEP IN THE PLAN, never a defect in the spec.** The spec
is owner-ruled. If a requirement needs a field that does not exist, **the plan
must add the field** — that is what plans are for.

**Never report a requirement as "impossible" and never suggest narrowing one.**
"Impossible" points the next reader at scoping down the spec, which is the
opposite of the repair.

🚫 **The spec is never edited by this skill or its findings.** A finding that
appears to require a spec change is an escalation to the owner, never an action.

### Reporting rules

- **Write the report to a FILE first and append as you go.** The final message
  is a summary; the file is the deliverable. _(Dispatched agents have completed
  full audits whose final text never reached the parent. The agent does not
  notice.)_
- **Record PLANNED items too.** A map that lists only holes cannot show what is
  safe to build on, and cannot be checked for completeness.
- **Report what could not be resolved**, naming the search run — never guess. An
  honest "unresolved" is what makes the PLANNED verdicts worth anything.
- 🔴 **If a partition returns ALL PLANNED with zero NAME-ONLY, hand-verify two
  PLANNED rows at random and show the working.** **An all-clear is the result
  most likely to be produced by not looking.**

### After the sweep — the dispatcher's job

1. **Consolidate into ONE numbered list** across all partitions. Never act on
   partial batches.
2. **Filter stale findings** if the plan moved during the sweep — and say so
   rather than counting them.
3. **Close every gap before epics are created.** That is the entire point of
   running it here; a filed-and-deferred gap is the failure this skill exists to
   prevent.
4. **Spot-verify any finding that names a file, line, or symbol** before acting.
   Auditors misread cites, and a correction carries the same evidence bar as the
   finding it replaces.

### What this does NOT cover

**Compositional defects.** Per-item traversal cannot see _"every phase
individually fine, the whole broken."_ Measured example: an end state that would
run **two concurrent reconcilers**, violating the premise of the design's own
no-multi-writer ruling — while every individual requirement was satisfied.

⇒ **Pair this with a compositional pass.** They are different lenses and neither
substitutes for the other. **The standard flow wants two audits, not eight.**

### Failure modes of this skill itself

| Failure                                          | Symptom                                 | Guard                                      |
| ------------------------------------------------ | --------------------------------------- | ------------------------------------------ |
| Folded into `verify-against-source` as redundant | "we already check coverage"             | The traversal direction differs; keep both |
| Run by the plan's author                         | Everything PLANNED                      | Dispatch it                                |
| Partitioned by plan section                      | False ABSENTs                           | Partition by spec item                     |
| Agent avoids NAME-ONLY                           | Zero NAME-ONLY across a large partition | Mandatory hand-verify of two rows          |
| Findings filed, not fixed                        | Gaps reach the beads anyway             | Close before epics                         |