/speck.analyze | speck | ClaudePluginHub

User Input

$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 command MUST run only after /speck.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 (.speck/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. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside /speck.analyze.

Execution Steps

1. Initialize Analysis Context

Extract prerequisite context from the auto-injected comment in the prompt:

<!-- SPECK_PREREQ_CONTEXT
{"MODE":"single-repo","FEATURE_DIR":"/path/to/specs/010-feature","AVAILABLE_DOCS":["specs/010-feature/spec.md","specs/010-feature/plan.md","specs/010-feature/tasks.md",".speck/memory/constitution.md"]}
-->

Use FEATURE_DIR and AVAILABLE_DOCS from this JSON.

Fallback: If the comment is not present (VSCode hook bug), run:

speck check-prerequisites --json --require-tasks --include-tasks

Parse JSON output to extract FEATURE_DIR and AVAILABLE_DOCS.

IMPORTANT: Do NOT invent or guess CLI paths. Use ONLY the path above.

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

2. Load Artifacts (Progressive Disclosure)

Use Read tool to load files from paths in AVAILABLE_DOCS. 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.md:

Principle validation rules

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 (derive slug based on imperative phrase; e.g., "User can upload file" → user-can-upload-file)
User story/action inventory: Discrete user actions with acceptance criteria
Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
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 (e.g., integration tasks before foundational setup tasks without dependency note)
Conflicting requirements (e.g., one requires Next.js while other specifies Vue)

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 the following structure:

Specification Analysis Report

ID	Category	Severity	Location(s)	Summary	Recommendation
A1	Duplication	HIGH	spec.md:L120-134	Two similar requirements ...	Merge phrasing; keep clearer version

(Add one row per finding; generate stable IDs prefixed by category initial.)

Coverage Summary Table:

Requirement Key	Has Task?	Task IDs	Notes

Constitution Alignment Issues: (if any)

Unmapped Tasks: (if any)

Metrics:

Total Requirements
Total Tasks
Coverage % (requirements with >=1 task)
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 /speck.implement
If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
Provide explicit command suggestions: e.g., "Run /speck.specify with refinement", "Run /speck.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"

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.)

CRITICAL: If remediation edits are approved and applied, any tasks that are modified with new requirements MUST be unchecked (changed from [X] to [ ]) in tasks.md so they will be re-implemented with the updated requirements.

Operating Principles

Context Efficiency

Minimal high-signal tokens: Focus on actionable findings, not exhaustive documentation
Progressive disclosure: Load artifacts incrementally; don't dump all content into analysis
Token-efficient output: Limit findings table to 50 rows; summarize overflow
Deterministic results: Rerunning without changes should produce consistent IDs and counts

Analysis Guidelines

NEVER modify files (this is read-only analysis)
NEVER hallucinate missing sections (if absent, report them accurately)
Prioritize constitution violations (these are always CRITICAL)
Use examples over exhaustive rules (cite specific instances, not generic patterns)
Report zero issues gracefully (emit success report with coverage statistics)

Context

$ARGUMENTS