/write-a-spec

name: write-a-spec
description: "Scope a feature end to end and write an implementation spec under specs/ from an accepted proposal — current-system mapping, goals/non-goals, a Decision Log for one-way-door choices, a live Open Questions backlog, and a real migration + test plan. Read when asked to write a spec, scope this feature, turn this proposal into a spec, plan the implementation, or break this into tasks. Do NOT fire on frame a proposal or write the PRD (sibling frame-a-proposal — a PRD frames a change before it is accepted; this skill starts once one is), record a decision or write the ADR (record-a-decision), write a postmortem (write-a-postmortem), or review this design (review-a-design) — those are separate skills. Complements the platform open-knowledge skill; does not replace it."
compatibility: "Any agent host with the OpenKnowledge MCP server configured. Installed project-local by `ok seed --pack software-lifecycle` (`ok-beta` for Beta)."
metadata:
  pack: "software-lifecycle"
  author: "Inkeep"
  repository: "https://github.com/inkeep/open-knowledge-skills"

Write a spec — scope a feature and commit an implementation spec

> This skill is pack guidance. The platform `/open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers spec-writing craft on top.

A spec is the contract between "we decided to build this" and "here is how it gets built." It is derived from an ACCEPTED proposal, maps the system that exists TODAY before proposing a change, and records its one-way-door choices in a Decision Log so the reasoning survives the author leaving. A spec that skips the current-system mapping, or resolves its open questions silently, is a liability — it reads authoritative while being unfounded.

`specs/` uses a folder-per-spec shape: `specs/NNN-name/` holding `spec.md`, and (when the work is actually going to be built) `plan.md` + `tasks.md`. The pack ships all three templates. `status` on `spec.md` flows `draft → ... → shipped`.

Autonomy mode

| Mode | Behavior | How entered | |---|---|---| | **Supervised** (default) | STOP at the Step 2 scoping gate for user confirmation of Goals / Non-goals / change shape. Route open decisions interactively. | Default when a user drives the session. | | **Headless** | Auto-confirm the scoping proposal after presenting it; auto-select routing decisions. All other gates (parent-proposal check, current-system mapping, Decision Log, validation, grounding) still enforced. | Explicit "don't wait for me", "just proceed", "run headless" — or non-interactive container environments. |

In headless mode, propose the scope AND proceed immediately; record in the Decision Log that scope was auto-confirmed without user sign-off.

---

Mandatory execution order

**Hard gates — do NOT skip ahead.** If you find yourself about to write `## Design` before you have read the actual code the change touches, STOP — you skipped Step 1.

0. **Find the parent proposal.** No accepted proposal behind a spec is a smell. 1. **Map the CURRENT system.** Read real code + prior specs + guides. Write what exists today, with pointers. 2. **Scoping STOP gate.** Propose Goals / Non-goals / change shape. In Supervised mode, WAIT. 3. **Create the spec folder + `spec.md`** from the `spec` template; allocate `NNN` by listing, not guessing. 4. **Fill Goals / Non-goals** — non-goals temporal, each with a reason. 5. **Design** — options considered, one chosen, why; one-way doors flow to the Decision Log. 6. **Decision Log** — append the section; each entry survives the author. 7. **Open Questions** — a live backlog, each with its closing evidence and decider. 8. **Migration + Test plan** — real states, real tiers, explicit gaps. 9. **`plan.md` + `tasks.md`** — only when the spec is going to be built. 10. **Link + validate** — backlinks, dead-links clean, frontmatter complete. 11. **Recap** — and what would move it out of `draft`.

---

Step 0: Find the parent proposal

A spec implements a decision that was already made. Before scoping anything, find the accepted proposal it derives from.

1. `exec("ls -A proposals/")` — surface the proposal set with frontmatter enrichment. 2. `exec("ls -A decisions/")` — an accepted proposal often has a matching frozen record here. 3. `search({ query: "<feature name or problem statement>" })` — semantic match across both folders when the name differs from the filename. 4. For the 1-2 strongest candidates, `exec("cat proposals/0004-x.md")` — read the accepted design and its unresolved questions in full; those unresolved questions become your Open Questions seed.

**Route on what you find:**

• **Accepted proposal exists** → note its path; it becomes `parent_proposal:` in the spec frontmatter. Proceed to Step 1.
• **Proposal exists but is not accepted** (`draft`, `fcp`, `rejected`) → STOP. A spec for an un-accepted proposal builds on sand. Surface this: "The proposal `<path>` is at `status: <x>`, not accepted. A spec should follow an accepted proposal. Want me to help get it accepted first, or proceed anyway?"
• **No proposal at all** → say so plainly: "There's no accepted proposal behind this feature. Specs derive from proposals — the proposal is where we argue *whether* to build; the spec is *how*. I can frame a proposal first (that's the `/frame-a-proposal` skill), or, if you acknowledge the risk, proceed straight to a spec and record that we skipped the proposal." If the user opts to proceed, record that choice in the Decision Log (Step 6) with its rationale. Do not silently skip it.

**HARD GATE:** do not create `spec.md` until the parent-proposal question is resolved one way or the other and, if skipped, acknowledged by the user.

---

Step 1: Map the CURRENT system before designing the change

The most common spec failure is designing against an imagined system. You cannot write a sound `## Design` or a real `## Migration` without knowing what the running system doe