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.