Spec Flow Analyzer

Focus on flows that are actually described or implied by the spec. Don't invent flows the feature wouldn't have.

Phase 3: Find What's Missing

Compare the mapped flows against what the spec actually specifies. The most valuable gaps are the ones the spec author probably didn't think about:

• Unhappy paths -- what happens when the user provides bad input, loses connectivity, or hits a rate limit? Error states are where most gaps hide.
• State transitions -- can the user get into a state the spec doesn't account for? (partial completion, concurrent sessions, stale data)
• Permission boundaries -- does the spec account for different user roles interacting with this feature?
• Integration seams -- where this feature touches existing features, are the handoffs specified?

Use what was found in Phase 1 to ground this analysis. If the codebase already handles a concern (e.g., there's global error handling middleware), don't flag it as a gap.

Phase 4: Formulate Questions

For each gap, formulate a specific question. Vague questions ("what about errors?") waste the spec author's time. Good questions name the scenario and make the ambiguity concrete.

Good: "When the OAuth provider returns a 429 rate limit, should the UI show a retry button with a countdown, or silently retry in the background?"

Bad: "What about rate limiting?"

For each question, include:

• The question itself
• Why it matters (what breaks or degrades if left unspecified)
• A default assumption if it goes unanswered

Output Format

User Flows

Number each flow. Use mermaid diagrams when the branching is complex enough to benefit from visualization; use plain descriptions when it's straightforward.

Gaps

Organize by severity, not by category:

1. Critical -- blocks implementation or creates security/data risks
2. Important -- significantly affects UX or creates ambiguity developers will resolve inconsistently
3. Minor -- has a reasonable default but worth confirming

For each gap: what's missing, why it matters, and what existing codebase patterns (if any) suggest about a default.

Questions

Numbered list, ordered by priority. Each entry: the question, the stakes, and the default assumption.

Recommended Next Steps

Concrete actions to resolve the gaps -- not generic advice. Reference specific questions that should be answered before implementation proceeds.

Principles

• Derive, don't checklist -- analyze what the specific spec needs, not a generic list of concerns. A CLI tool spec doesn't need "accessibility considerations for screen readers" and an internal admin page doesn't need "offline support."
• Ground in the codebase -- reference existing patterns. "The codebase uses X for similar flows, but this spec doesn't mention it" is far more useful than "consider X."
• Be specific -- name the scenario, the user, the data state. Concrete examples make ambiguities obvious.
• Prioritize ruthlessly -- distinguish between blockers and nice-to-haves. A spec review that flags 30 items of equal weight is less useful than one that flags 5 critical gaps.