b4san/spec-analysis

Specification & Planning Analysis

Overview

Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (spec.md, plan.md, tasks.md) before implementation.

STRICTLY READ-ONLY: Do not modify any files. Output a structured analysis report. Offer an optional remediation plan.

Constitution Authority: The project constitution (.specify/memory/constitution.md) is non-negotiable.

Execution Steps

1. Initialize Analysis Context:

   • Load FEATURE_DIR/spec.md (or specs/spec.md).
   • Load FEATURE_DIR/plan.md (or specs/plan.md).
   • Load FEATURE_DIR/tasks.md (or specs/tasks.md).
   • Ensure all files exist; if not, report which are missing (though tasks might not exist yet if only planning).

2. Load Artifacts (Progressive Disclosure):

   • Load only necessary portions relevant to the feature.
   • Load .specify/memory/constitution.md for validation.

3. Build Semantic Models:

   • Requirements inventory: Functional + non-functional requirements.
   • User story/action inventory: User actions + acceptance criteria.
   • Task coverage mapping: Map task to requirement/story.
   • Constitution rule set: Principle names and MUST statements.

4. Detection Passes:

   • Duplication: Near-duplicate requirements.
   • Ambiguity: Vague adjectives ("fast", "robust") without metrics. Unresolved placeholders (TODO, ???).
   • Underspecification: Verbs missing objects/outcomes. User stories missing acceptance criteria.
   • Constitution Alignment: Conflict with MUST principles. Missing mandated sections.
   • Coverage Gaps: Requirements with zero tasks. Tasks with no mapped requirement.
   • Inconsistency: Terminology drift. Data entities in plan but absent in spec. Task order contradictions.

5. Severity Assignment:

   • CRITICAL: Violates constitution, missing core artifact, blocking requirement with zero coverage.
   • HIGH: Duplicate/conflicting requirement, ambiguous security/performance, untestable AC.
   • MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case.
   • LOW: Style/wording improvements.

6. Produce Compact Analysis Report:

   • Output a Markdown report with a findings table: | ID | Category | Severity | Location | Summary | Recommendation |
   • Coverage Summary Table: Requirement Key | Has Task? | Task IDs | Notes
   • Metrics: Total Requirements, Total Tasks, Coverage %, Ambiguity Count.

7. Provide Next Actions:

   • Recommend resolving CRITICAL issues before implementation.
   • Provide explicit suggestions (e.g., "Refine spec", "Adjust plan").

8. Offer Remediation:

   • Ask if the user wants concrete remediation edits for top N issues.

Operating Principles

• Context Efficiency: Focus on actionable findings.
• NEVER modify files automatically (read-only analysis).
• NEVER hallucinate missing sections.
• Prioritize constitution violations.