Quality Analysis
The /speckit.analyze command performs a comprehensive, read-only consistency and quality analysis across your spec artifacts. Run it after generating tasks, before implementation.
When to Use
Run after /speckit.tasks produces tasks.md, before /speckit.implement.
What It Analyzes
The command reads three core artifacts plus supporting files:
| File | What It Extracts |
|---|---|
spec.md | Requirements, user stories, acceptance criteria, edge cases |
plan.md | Architecture choices, data model, phases, constraints |
tasks.md | Task IDs, descriptions, phases, parallel markers, file paths |
constitution.md | Principles, MUST/SHOULD normative statements |
design.md | Component specs, variants, user flows, token references |
branding.md | Design tokens, color values |
Detection Passes
A. Duplication Detection
Identifies near-duplicate requirements across artifacts. Recommends consolidation.
B. Ambiguity Detection
Flags vague terms lacking measurable criteria:
- "fast", "scalable", "secure", "intuitive", "robust"
- Unresolved placeholders:
TODO,TKTK,???,<placeholder>
C. Underspecification
- Requirements with verbs but missing measurable outcomes
- User stories missing acceptance criteria
- Tasks referencing files not defined in spec/plan
D. Constitution Alignment
- Requirements conflicting with MUST principles (always CRITICAL)
- Missing mandated sections or quality gates
E. Coverage Gaps
- Requirements with zero associated tasks
- Tasks with no mapped requirement
- Non-functional requirements not reflected in tasks
F. Design & Branding Consistency
Only runs if design.md or branding.md exist:
- Hardcoded color values instead of token references
- Tokens referenced but not defined in branding
- Missing accessibility requirements (ARIA, keyboard, contrast)
- User flows missing error states
- WCAG 2.1 AA contrast failures
G. Inconsistency
- Terminology drift (same concept named differently)
- Data entities in plan but not in spec (or vice versa)
- Task ordering contradictions
- Conflicting technology choices
Severity Levels
| Severity | Criteria |
|---|---|
| CRITICAL | Constitution violation, missing core artifact, blocking requirement with zero coverage |
| HIGH | Duplicate/conflicting requirement, ambiguous security/performance attribute, untestable criterion |
| MEDIUM | Terminology drift, missing non-functional coverage, underspecified edge case |
| LOW | Style/wording improvements, minor redundancy |
Output Format
The analysis produces a Markdown report (displayed, not written to file):
Findings Table
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|---|---|---|---|---|---|
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements... | Merge; keep clearer version |
| D1 | Constitution | CRITICAL | plan.md:L45 | Missing rate limiting | Add NFR per Article X |
Limited to 50 findings. Remaining items summarized.
Coverage Summary
| Requirement Key | Has Task? | Task IDs | Notes |
|---|---|---|---|
| user-can-login | Yes | T1.1, T1.2 | |
| user-can-export | No | — | Gap: no tasks |
Quality Score
| Category | Max | Score | Details |
|---|---|---|---|
| Completeness | 30 | /30 | All sections filled, no TODOs |
| Consistency | 25 | /25 | Constitution aligned, consistent terms |
| Testability | 25 | /25 | GIVEN/WHEN/THEN for all requirements |
| Clarity | 20 | /20 | No vague terms, clear language |
| TOTAL | 100 | /100 |
Rating: Excellent (90+) | Good (80+) | Fair (70+) | Poor (<70)
Maturity Assessment
- Current maturity level
- Recommended maturity (based on score and coverage)
- Knowledge coverage percentage
Next Actions
Based on the findings:
| Situation | Recommendation |
|---|---|
| CRITICAL issues | Resolve before /speckit.implement |
| Only LOW/MEDIUM | Safe to proceed, improvement suggestions provided |
| Score < 70 | Consider running /speckit.clarify to fill gaps |
| Design issues | Run /speckit.design to fix token references |
Remediation
After the report, the command offers:
"Would you like me to suggest concrete remediation edits for the top N issues?"
Suggestions are presented — never applied automatically. You choose which to accept.
Operating Principles
- Read-only — Never modifies files
- Deterministic — Rerunning without changes produces consistent results
- Token-efficient — Focuses on high-signal findings, limits to 50
- Constitution authority — Violations are always CRITICAL; constitution is non-negotiable within analysis scope