to-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# To-spec

Synthesis only. Takes the accumulated decisions from a completed
wayfinder map and writes them into a formal spec. If the map hasn't
actually answered something this needs, that's a sign the map wasn't
complete — go back to wayfinder and add a ticket rather than inventing
an answer.

## Process

1. **Read `.agent/state.json`** to get the `doc_tier` and confirm
   `status` is `"mapping"` with all map tickets resolved. Read the
   wayfinder map at `map_ref`.

2. **Explore the repository** to understand the current codebase state.
   Use domain vocabulary from `CONTEXT.md` and respect existing ADRs.

3. **Identify testing seams** — prefer existing public boundaries. If
   new seams are needed, propose them at the highest architectural level.
   Use `/codebase-design` seam discipline: place seams at volatile
   boundaries, not at every boundary. One adapter = hypothetical seam;
   two adapters = real seam.

4. **Write the spec at a depth matching the tier** (`reference/doc-tiers.md`):
   - **Script tier**: no separate spec file. The `CONTEXT.md` summary
     from wayfinder grilling is enough; skip straight to
     `skills/to-tickets/SKILL.md`.
   - **Tool tier**: a short spec (~half page) covering problem
     statement, solution, and 3-6 acceptance criteria.
   - **App / system tier**: full spec using the template below.

   ### Spec template (app/system tier)

   - **Problem statement** — what the user is experiencing.
   - **Solution** — what the user will experience once done.
   - **User stories** — numbered, "As a [role], I want [action], so
     that [outcome]" format.
   - **Implementation decisions** — modules, interfaces, architectural
     choices. Use `/codebase-design` vocabulary (depth, seam, module,
     adapter, locality) when describing boundaries and interfaces.
     No file paths (those belong in tickets).
   - **Testing decisions** — seams, modules needing tests, prior art.
   - **Out of scope** — explicitly excluded items.

5. **Do not add scope that wasn't discussed.** If something seems like
   an obvious gap, flag it as a question back to the user.

   **Evidence gate:** every implementation decision in the spec must trace
   to a resolved decision on the map — quote or reference it. If a decision
   the spec needs isn't on the map, that's incomplete fog: go back to
   wayfinder and add a ticket. Do not invent the answer here.

6. **Save** to `docs/agents/spec.md` and update `.agent/state.json`
   status to `"implementing"`.

7. **Hand off** to `skills/to-tickets/SKILL.md` directly.

## What this skill must never do

- Never conduct new interview questions — that's wayfinder's job.
- Never produce a spec for script-tier projects.
- Never add scope beyond what was discussed on the wayfinder map.

From lynchypin/project-onboard, MIT.

More from lynchypin/project-onboard