speckit-analyze

---

name: speckit-analyze description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.

User Input

Copy$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (spec.md, plan.md, tasks.md) before implementation. This skill MUST run only after /speckit.tasks has successfully produced a complete tasks.md.

Operating Constraints

STRICTLY READ-ONLY: Do not modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).

Constitution Authority: The project constitution (.specify/memory/constitution.md) is non-negotiable within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks - not dilution, reinterpretation, or silent ignoring of the principle.

Memory Integration

This skill is read-only analysis - no memory search/save needed.

Constitution Alignment

This skill validates alignment with project principles:

• All artifacts must follow constitution guidelines
• Constitution violations are automatically CRITICAL severity

Execution Steps

1. Initialize Analysis Context

Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md

Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).

2. Load Artifacts (Progressive Disclosure)

Load only the minimal necessary context from each artifact:

From spec.md:

• Overview/Context
• Functional Requirements
• Non-Functional Requirements
• User Stories
• Edge Cases (if present)

From plan.md:

• Architecture/stack choices
• Data Model references
• Phases
• Technical constraints

From tasks.md:

• Task IDs
• Descriptions
• Phase grouping
• Parallel markers [P]
• Referenced file paths

From constitution:

• Load .specify/memory/constitution.md for principle validation

3. Build Semantic Models

Create internal representations (do not include raw artifacts in output):

• Requirements inventory: Each functional + non-functional requirement with a stable key
• User story/action inventory: Discrete user actions with acceptance criteria
• Task coverage mapping: Map each task to one or more requirements or stories
• Constitution rule set: Extract principle names and MUST/SHOULD normative statements

4. Detection Passes (Token-Efficient Analysis)

Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.

A. Duplication Detection

• Identify near-duplicate requirements
• Mark lower-quality phrasing for consolidation

B. Ambiguity Detection

• Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
• Flag unresolved placeholders (TODO, TKTK, ???, <placeholder>, etc.)

C. Underspecification

• Requirements with verbs but missing object or measurable outcome
• User stories missing acceptance criteria alignment
• Tasks referencing files or components not defined in spec/plan

D. Constitution Alignment

• Any requirement or plan element conflicting with a MUST principle
• Missing mandated sections or quality gates from constitution

E. Coverage Gaps

• Requirements with zero associated tasks
• Tasks with no mapped requirement/story
• Non-functional requirements not reflected in tasks (e.g., performance, security)

F. Inconsistency

• Terminology drift (same concept named differently across files)
• Data entities referenced in plan but absent in spec (or vice versa)
• Task ordering contradictions
• Conflicting requirements

5. Severity Assignment

Use this heuristic to prioritize findings:

• CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
• HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
• MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case
• LOW: Style/wording improvements, minor redundancy not affecting execution order

6. Produce Compact Analysis Report

Output a Markdown report (no file writes) with:

Specification Analysis Report

| ID | Category | Severity | Location(s) | Summary | Recommendation |

Coverage Summary Table Constitution Alignment Issues (if any) Unmapped Tasks (if any) Metrics: Total Requirements, Total Tasks, Coverage %, Ambiguity Count, Duplication Count, Critical Issues Count

7. Provide Next Actions

At end of report, output a concise Next Actions block:

• If CRITICAL issues exist: Recommend resolving before /speckit.implement
• If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
• Provide explicit command suggestions

8. Offer Remediation

Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)

Handoff

After completing this skill:

• Fix issues: Address CRITICAL/HIGH issues before proceeding
• Start implementing: Run /speckit.implement if analysis is clean

References

• spec.md - Feature specification
• plan.md - Implementation plan
• tasks.md - Task list
• .specify/memory/constitution.md - Project principles