speckit-analyze

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Kit Analyze Skill

When to Use

适用场景

You have
```
spec.md
```
,
```
plan.md
```
, and
```
tasks.md
```
and need a read-only consistency analysis before implementation.

当你拥有

spec.md

、

plan.md

和

tasks.md

，且需要在实施前进行只读一致性分析时使用。

Inputs

输入

```
specs/<feature>/spec.md
```
,
```
plan.md
```
,
```
tasks.md
```
```
.specify/memory/constitution.md
```
Any user concerns or focus areas from the request

```
specs/<feature>/spec.md
```
,
```
plan.md
```
,
```
tasks.md
```
```
.specify/memory/constitution.md
```
请求中提及的任何用户关注点或重点领域

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 a complete

tasks.md

exists (typically after speckit-tasks).

在实施前，识别三个核心工件（

spec.md

、

plan.md

、

tasks.md

）之间的不一致、重复、模糊表述和规范不足的内容。该Skill必须仅在完整的

tasks.md

生成后运行（通常在执行speckit-tasks之后）。

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 edits are performed 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. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside this skill.

严格只读：禁止修改任何文件。输出结构化的分析报告。可提供可选的修复方案（在手动执行任何后续编辑前，必须获得用户明确批准）。

章程权威性：项目章程（

.specify/memory/constitution.md

）在本分析范围内具有不可协商性。违反章程的问题自动判定为CRITICAL级别，需要调整规范、计划或任务——不得弱化、重新解读或默认忽略相关原则。若原则本身需要变更，必须在本Skill之外通过单独、明确的章程更新操作完成。

Workflow

工作流程

1. Initialize Analysis Context

1. 初始化分析上下文

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 the missing prerequisite skill or script). For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

从仓库根目录运行一次

.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks

，并解析JSON获取FEATURE_DIR和AVAILABLE_DOCS。推导绝对路径：

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

若任何必要文件缺失，则终止并输出错误信息（指导用户运行缺失的前置技能或脚本）。对于参数中的单引号，如"I'm Groot"，使用转义语法：例如'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. Load Artifacts (Progressive Disclosure)

2. 加载工件（渐进式披露）

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

仅从每个工件中加载必要的最少上下文：

来自spec.md：

概述/上下文
功能需求
非功能需求
用户故事
边缘情况（若存在）

来自plan.md：

架构/技术栈选择
数据模型引用
阶段
技术约束

来自tasks.md：

任务ID
描述
阶段分组
并行标记[P]
引用的文件路径

来自章程：

加载
```
.specify/memory/constitution.md
```
用于原则验证

3. Build Semantic Models

3. 构建语义模型

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

创建内部表示（输出中不包含原始工件内容）：

需求清单：每个功能与非功能需求对应一个稳定键（根据祈使短语生成短标识；例如，"User can upload file" →
```
user-can-upload-file
```
）
用户故事/操作清单：带有验收标准的独立用户操作
任务覆盖映射：将每个任务映射到一个或多个需求或故事（通过关键词/显式引用模式如ID或关键短语进行推断）
章程规则集：提取原则名称和MUST/SHOULD规范性声明

4. Detection Passes (Token-Efficient Analysis)

4. 检测环节（高效Token分析）

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

聚焦高信号发现。最多保留50项发现；剩余内容汇总到溢出摘要中。

A. Duplication Detection

A. 重复检测

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

识别近似重复的需求
标记质量较低的表述以便合并

B. Ambiguity Detection

B. 模糊性检测

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

标记缺乏可衡量标准的模糊形容词（如fast、scalable、secure、intuitive、robust）
标记未解决的占位符（如TODO、TKTK、???、
```
<placeholder>
```
等）

C. Underspecification

C. 规范不足检测

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

有动词但缺少对象或可衡量结果的需求
未对齐验收标准的用户故事
引用了spec/plan中未定义的文件或组件的任务

D. Constitution Alignment

D. 章程一致性检测

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

任何与MUST原则冲突的需求或计划元素
缺少章程要求的章节或质量关卡

E. Coverage Gaps

E. 覆盖缺口检测

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

无关联任务的需求
未映射到需求/故事的任务
未在任务中体现的非功能需求（如性能、安全）

F. Inconsistency

F. 不一致性检测

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)

术语漂移（同一概念在不同文件中命名不同）
计划中引用但规范中未提及的数据实体（反之亦然）
任务顺序矛盾（例如，在无依赖说明的情况下，集成任务早于基础设置任务）
冲突的需求（例如，一个要求Next.js，另一个指定Vue）

5. Severity Assignment

5. 严重性分配

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

使用以下启发式规则对发现的问题进行优先级排序：

CRITICAL（严重）：违反章程的MUST原则、核心规范工件缺失，或阻碍基线功能的无覆盖需求
HIGH（高）：重复或冲突的需求、模糊的安全/性能属性、不可测试的验收标准
MEDIUM（中）：术语漂移、非功能需求的任务覆盖缺失、规范不足的边缘情况
LOW（低）：风格/措辞改进、不影响执行顺序的轻微冗余

6. Produce Compact Analysis Report

6. 生成简洁分析报告

Output a Markdown report (no file writes) with the following structure:

输出以下结构的Markdown报告（不写入文件）：

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

ID	类别	严重性	位置	摘要	建议
A1	重复检测	HIGH	spec.md:L120-134	两项相似的需求...	合并表述；保留更清晰的版本

（每项发现添加一行；生成以类别首字母为前缀的稳定ID。）

覆盖情况汇总表：

需求键	是否有任务？	任务ID	备注

章程一致性问题：（若存在）

未映射任务：（若存在）

指标：

总需求数
总任务数
覆盖率（有至少1个任务的需求占比）
模糊性问题数
重复问题数
严重问题数

7. Provide Next Actions

7. 提供后续操作建议

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 next-step suggestions: e.g., "Run speckit-specify to refine requirements", "Run speckit-plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"

在报告末尾输出简洁的后续操作模块：

若存在CRITICAL问题：建议在运行speckit-implement前解决
若仅有LOW/MEDIUM问题：用户可继续实施，但需提供改进建议
提供明确的下一步建议：例如，"运行speckit-specify以优化需求"、"运行speckit-plan以调整架构"、"手动编辑tasks.md以添加'performance-metrics'的覆盖任务"

8. Offer Remediation

8. 提供修复建议

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

询问用户："是否需要我为前N个问题提供具体的修复编辑建议？"（请勿自动应用这些建议。）

Outputs

输出

Read-only analysis report in the response (no file writes)

响应中返回只读分析报告（不写入文件）

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

最小高信号Token：聚焦可执行的发现，而非详尽的文档内容
渐进式披露：增量加载工件；不要将所有内容都导入分析
高效Token输出：将发现表限制为50行；汇总超出部分
确定性结果：无变更重新运行应产生一致的ID和计数

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)

绝对禁止修改文件（这是只读分析）
绝对禁止虚构缺失的章节（若缺失，如实报告）
优先处理章程违规问题（这些始终为CRITICAL级别）
使用示例而非详尽规则（引用具体实例，而非通用模式）
优雅报告无问题情况（输出包含覆盖统计的成功报告）

Context

上下文

the user's request and any stated focus areas

用户的请求及任何指定的重点领域