Spec Drafting Workflow

A spec is good when a reviewer can disagree with it precisely — point at a sentence, dispute the claim, propose an alternative. This skill drafts feature and system specs to that bar: an evidenced problem, goals fenced in by non-goals, real options honestly costed, behavior pinned down with scenarios, and acceptance criteria that decide "done" without convening a meeting.

When to use this skill

• A feature idea or problem statement needs turning into a reviewable spec or requirements doc
• Scope keeps creeping because goals and non-goals were never written down
• Stakeholders "agree" verbally but a written artifact is needed to expose the disagreements
• An engineering design needs options compared before the code makes the decision by default
• Acceptance criteria are needed so that "done" stops being a negotiation

Workflow

1. Write the problem statement in the user's terms, with evidence it exists: a ticket count, a measured drop-off, a quote, a cost. A problem with no evidence is a solution looking for a sponsor — label it an assumption to validate, not a foundation.
2. State goals as observable outcomes, then write at least three non-goals. Non-goals are the fence that keeps scope out; every one written now is a meeting skipped later.
3. List the constraints the design must obey rather than choose: deadlines, compatibility, budget, compliance, platform limits. Mislabeling a preference as a constraint is how weak designs get immunized against review — challenge each one once.
4. Develop two or three credible options, each with an honest cost: build time, operational load, risk, and what it forecloses later. If only one option appears, the design happened before the spec; go find the alternative a smart skeptic would propose.
5. Choose, and justify the choice in terms of the goals and constraints — never taste. Record the losing options and why they lost; that paragraph saves the next person a month.
6. Pin down behavior with concrete scenarios: given/when/then for the main flows, plus the two ugliest edge cases you can construct. Prose describes; scenarios commit.
7. List risks and open questions, each with an owner and a resolve-by date. An open question without an owner is a decision being made silently, by the calendar.
8. Write acceptance criteria as testable statements a person who did not write the spec could check alone. "Fast" is not checkable; "p95 under 300 ms at 100 concurrent users" is.
9. Circulate for written review. Every comment ends as a change, a logged decision with a reason, or an open question with an owner — comments that simply evaporate come back later as bugs.

Output format

# Spec: <name>        Status: draft | in review | approved        Owner: <name>

Problem (with evidence)
Goals / Non-goals (>= 3 non-goals)
Constraints (each one challenged once, then honored)
Options considered: A / B / C — costs, risks, why the losers lost
Chosen approach — justified against the goals
Behavior: scenarios (given / when / then) + the two ugliest edge cases
Risks and open questions — owner and resolve-by date on every line
Acceptance criteria — numbered, testable by a stranger
Decision log — what changed in review, and why

Quality bar

• A reviewer can quote the exact sentence they dispute — no load-bearing vagueness anywhere.
• Every "should" has been upgraded to "must", downgraded to "may", or deleted.
• The non-goals survive stakeholder contact without being quietly deleted.
• Acceptance criteria are executable by someone outside the authoring team and immune to wishful interpretation.
• The spec records why, not just what: rejected options and review decisions stay in the document as its institutional memory.