clarify-spec

Clarify Spec — Internal Consistency Checker

Find contradictions, gaps, and ambiguities within a spec. This is a fast, single-model check that runs BEFORE the more expensive multi-model cross-review.

Why Clarify Before Review?

Cross-review (review-spec) is expensive — it calls multiple models. Clarify catches obvious structural issues first, so cross-review can focus on deeper problems.

Instructions

Step 1: Locate and Read Spec

If $ARGUMENTS is provided, use it as the spec directory path. Otherwise, search for spec directories and ask the user.

Read all three files: requirements.md, design.md, tasks.md.

Step 2: Traceability Check

Build a mapping:

Requirement ID → Design Section → Task Number

Report:

• Requirements with NO corresponding design section → Gap
• Design sections with NO corresponding task → Gap
• Tasks with NO requirement reference → Orphan (may be intentional, flag for review)

Step 3: EARS Format Check

For each acceptance criterion in requirements.md:

• Does it use EARS syntax (WHEN/IF/WHILE/WHERE...SHALL)?
• Is it testable? (Could a machine verify pass/fail?)
• Does it avoid vague terms? ("quickly", "user-friendly", "efficient")

Report non-EARS criteria as Format Issue.

Step 4: Dependency Check

For tasks.md:

• Are Phase dependencies declared? (_Depends on: Phase N_)
• Is there any circular dependency?
• Are [HUMAN] tasks blocking AI tasks unnecessarily?

Step 5: Contradiction Check

Look for:

• Requirement A says "SHALL" but Requirement B says the opposite
• Design specifies a timeout but no requirement mentions timeout behavior
• Task order contradicts design data flow

Step 6: Auto-Fix + Report

For each finding, classify:

• Auto-fixable: Missing _Requirements:_ tags, format issues → fix directly
• Needs human decision: Contradictions, scope gaps → list in report

Generate clarify-notes.md in the spec directory with:

1. Issues found (by category)
2. Auto-fixes applied
3. Items needing human decision

Ask: "Should I proceed to cross-review (/review-spec)?"