speckit-analyze-zh

User input

$ARGUMENTS

YouMUSTconsider the user input (if not empty) before proceeding.

Goal

Before implementation, identify inconsistencies, duplications, ambiguities, and underspecified items among the three core artifacts (spec.md、plan.md、tasks.md). This command MUST only run after speckit-tasks successfully generates a complete tasks.md .

Operating constraints

Strictly read-only：Do notmodify any files. Output a structured analysis report. Provide an optional remediation plan (the user MUST explicitly approve before manually invoking any subsequent editing command).

Constitution authority: the project constitution (.specify/memory/constitution.md) isnon-negotiablewithin the scope of this analysis. Constitution conflicts are automatically critical level and require adjusting the spec, plan, or tasks—not diluting, reinterpreting, or silently ignoring principles. If the principles themselves need to change, this MUST occur in a separate, explicit constitution update outside of speckit-analyze .

Execution steps

scripts: sh: .specify/scripts/bash/check-prerequisites.sh --json ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json

1. Initialize analysis context

Run once from the repository root {SCRIPT} and parse the JSON to obtain FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:

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

If any required file is missing, abort and display an error message (instructing the user to run the missing prerequisite command). For single quotes in arguments, such as "I'm Groot", use the escape syntax: e.g. 'I'''m Groot' (or use double quotes if possible: "I'm Groot").

2. Load artifacts (progressive disclosure)

Load only the minimum necessary context for each artifact:

From spec.md:

• Overview/context
• Functional requirements
• Non-functional requirements
• User stories
• Edge cases (if present)

From plan.md:

• Architecture/tech stack choices
• Data model references
• Phases
• Technical constraints

From tasks.md:

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

From constitution:

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

3. Build semantic model

Create an internal representation (do not include raw artifacts in the output):

• Requirements inventory: each functional + non-functional requirement with a stable key (derive a slug from the imperative sentence; e.g., "Users can upload files" → 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 (inferred via keyword/explicit reference patterns such as IDs or keywords)
• Constitution rule set: extract principle names and MUST/SHOULD normative statements

4. Detection Process (High-Efficiency Token Analysis)

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

A. Duplicate Detection

• Identify near-duplicate requirements
• Flag lower-quality wording for merging

B. Ambiguity Detection

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

C. Underspecification

• Requirements with a verb but missing an object or measurable outcome
• User stories lacking acceptance criteria alignment
• Tasks that reference files or components not defined in the spec/plan

D. Charter Alignment

• Any requirement or plan element that conflicts with a MUST principle
• Missing sections or quality gates specified in the charter

E. Coverage Gaps

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

F. Inconsistency

• Terminology drift (the same concept has different names across files)
• Data entities referenced in the plan but missing from the spec (or vice versa)
• Task ordering contradictions (e.g., an integration task before a foundational setup task with no dependency note)
• Conflicting requirements (e.g., one requires Next.js while another specifies Vue)

5. Severity Assignment

Use this heuristic to prioritize findings:

• Critical: violates a charter MUST, missing core spec artifact, or a zero-coverage requirement that blocks essential functionality
• High: duplicate or conflicting requirements, vague security/performance attributes, untestable acceptance criteria
• Medium: terminology drift, missing non-functional task coverage, underspecified edge cases
• Low: style/wording improvements, minor redundancy that does not affect execution order

6. Generate a Compact Analysis Report

Output a Markdown report (do not write to a file) with the following structure:

Spec Analysis Report

ID	Category	Severity	Location	Summary	Recommendation
A1	Duplicate	High	spec.md:L120-134	Two similar requirements ...	Merge wording; keep the clearer version

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

Coverage Summary Table:

Requirement Key	Has Task?	Task ID	Notes

Charter Alignment Issues:(if any)

Unmapped Tasks:(if any)

Metrics:

• Total Requirements
• Total Tasks
• Coverage % (requirements with >=1 task)
• Ambiguity Count
• Duplicate Count
• Critical Issue Count

7. Provide Next Actions

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

• If there are critical issues: suggest resolving before speckit-implement before resolving
• If only low/medium: the user may continue, but provide improvement suggestions
• Provide clear command suggestions: e.g., "Use improved run speckit-specify", "Run speckit-plan adjust architecture", "manually edit tasks.md to add coverage for 'performance-metrics'"

8. Provide remediation measures

Ask the user: "Do you want me to suggest specific remediation edits for the top N issues?" (Do not automatically apply them.)

Operating principles

Context efficiency

• Minimal high-signal tokens: focus on actionable findings, not exhaustive documentation
• Progressive disclosure: load artifacts incrementally; do not pour everything into the analysis
• Efficient token output: limit the 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 a read-only analysis)
• Never fabricate missing sections(if missing, report accurately)
• Prioritize charter violations(these are always critical)
• Use examples rather than exhaustive rules(cite specific instances, not generic patterns)
• Report zero issues gracefully(issue a success report with coverage statistics)

Context

{ARGS}