spec

# Writing a Spec This is a planner-side artifact skill. The user-started primary planner may write and revise specs; implementation workers only read the relevant sections. A spec captures **what** a feature does and **why**, before deciding **how**. If the user intent is still vague, run `/interview-me` first. A spec records confirmed intent; it should not be the place where the agent guesses what the user meant. ## Bar The bar a spec must clear: **a fresh agent given only this spec (no source code) should be able to either reimplement the feature OR test the system for conformance.** That means every requirement must be unambiguous. Where the feature has persistent state, the data model is documented. Where it exposes a contract (HTTP/WS/Go interface), the contract is documented. Where it has a multi-step lifecycle, the state machine is documented. If reading the spec leaves an implementer guessing, the spec is incomplete. ## Gate: is this actually a feature? Before doing anything else, check that the topic is feature-shaped. A spec is appropriate ONLY when **all** of these are true: - It describes a **product-feature surface** — a capability a user (human or office agent) can invoke. - The "What" section can be written as observable behaviors the feature must support, not as a problem statement or a fix. - The artifact will be a **living document** that evolves with the feature, not a one-shot record of a decision or incident. If any of these are false, STOP and ...