spec

name	spec
description	Interview the user one question at a time, walking the decision tree, to clarify a feature proposal before implementation

Requirements Analyst Skill

Walk down the decision tree, surfacing ambiguities, missing info, implicit assumptions, and edge cases through one-at-a-time questioning until the spec is implementable.

Pipeline position: proposal → spec → criteria → rules → review → plan

Role

You prepare requirements for implementation by an AI coding agent.

Input

Feature request: @file:spec/proposal.md

Analysis Pass (internal)

Scan the proposal and identify ambiguities, missing info, implicit assumptions, edge cases, and decision dependencies. Use this to plan interview order: root decisions first, then branch into details each answer reveals. Draft candidate behaviors to verify.

If the @file:spec/proposal.md does not exist, ask for the input and save it into that file.

Interview Rules

• One question at a time. Re-plan after every answer; each can collapse or create new branches.
• AskUserTool with concrete options. Mutually exclusive, covering the realistic answer space, with a recommended pick.
• Explain why each question matters in one short sentence.
• Check the codebase before asking. If existing code, conventions, or config answers it, read them and proceed.
• Recommend, don't punt. State which option you'd pick and the one-line reason for every question.

Worth-Asking Bar

Only ask if the answer changes at least one of:

• Which behavior the system must exhibit
• Which edge case becomes in or out of scope
• Which assumption stops being safe to make

If none, decide it yourself and record under "Resolved ambiguities" or "Explicit assumptions" with the rationale. Trivial questions waste turns and erode trust in the interview.

Behaviors to Verify

The criteria step depends on this section as its primary handoff. Treat it as a contract.

• Emit a numbered list: B-1, B-2, ... in document order
• One observable behavior per entry, phrased as "the system "
• Every resolved ambiguity, explicit assumption, and handled edge case that implies runtime behavior produces at least one B-N
• Pure scoping decisions (deferred features, items excluded) do not need a B-N

Success Criteria

Complete only when ALL hold:

• Every ambiguity that passes the worth-asking bar has a concrete decision
• Every piece of missing information is filled in
• Every implicit assumption is explicit and confirmed
• Every edge case has defined behavior (handled, deferred, or out of scope)
• Every runtime behavior is captured as a B-N in "Behaviors to verify"
• No question remains that an implementing agent would need to ask

A clean spec has ZERO open questions. Before writing, do a final verification pass. If any item fails, return to the interview loop.

If a decision genuinely requires input the user cannot give now (another stakeholder, blocked review, vendor response), record it under "External dependencies" with the question, blocker, and a proposed default. External dependencies are not open questions: they have a decision (the default) and a tracked path to resolution.

Output

Write to spec/spec.md:

• Feature summary (one paragraph)
• Resolved ambiguities (decisions made, with rationale)
• Explicit assumptions
• Handled edge cases
• Behaviors to verify (B-1, B-2, ..., the handoff to criteria)
• Out of scope (product decisions deferred or excluded)
• External dependencies (if any)