Back to Details

spec-inspect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

spec-inspect — Specification Quality Checker

spec-inspect — 规格文档质量检查工具

Automatically validates spec-generator output (requirement.md, design.md, tasks.md) and reports quality issues.
自动验证spec-generator输出的文档（requirement.md、design.md、tasks.md）并报告质量问题。

Language Rules

语言规则

  1. Auto-detect input language → output in the same language
  2. Japanese input → Japanese report output
  3. English input → English report output
  4. Explicit override takes priority (e.g., "in English", "日本語で")
  1. 自动检测输入语言 → 输出与输入语言一致
  2. 日语输入 → 生成日语报告
  3. 英语输入 → 生成英语报告
  4. 显式设置优先级更高（例如："in English"、"日本語で"）

When to Run

运行时机

  • After spec-generator completes (auto-suggested)
  • Before registering Issues with spec-to-issue
  • After updating specification documents
  • spec-generator完成后（自动推荐）
  • 使用spec-to-issue注册Issue之前
  • 更新规格文档之后

Execution Flow

执行流程

Step 1: Locate Project Path

步骤1：定位项目路径

Identify the 
.specs/{project-name}/
path from user input or current context.
Validation:
  • .specs/{project-name}/requirement.md
    exists
  • .specs/{project-name}/design.md
    exists
  • .specs/{project-name}/tasks.md
    exists
If any file is missing, display an error message and exit.
从用户输入或当前上下文识别
.specs/{project-name}/
路径。
验证项:
  • .specs/{project-name}/requirement.md
    存在
  • .specs/{project-name}/design.md
    存在
  • .specs/{project-name}/tasks.md
    存在
若任何文件缺失，显示错误信息并退出。

Step 2: Read Specifications

步骤2：读取规格文档

Read all three specification files:
requirement_content = Read(".specs/{project-name}/requirement.md")
design_content = Read(".specs/{project-name}/design.md")
tasks_content = Read(".specs/{project-name}/tasks.md")
读取所有三个规格文件：
requirement_content = Read(".specs/{project-name}/requirement.md")
design_content = Read(".specs/{project-name}/design.md")
tasks_content = Read(".specs/{project-name}/tasks.md")

Optional: load coding rules if available

可选：若存在则加载编码规则

coding_rules = Read("docs/coding-rules.md") or None
coding_rules = Read("docs/coding-rules.md") or None

Also check CLAUDE.md / AGENTS.md for alternative path

同时检查CLAUDE.md / AGENTS.md中的替代路径

undefined
undefined

Step 3: Run Quality Checks

步骤3：运行质量检查

Execute the following checks sequentially. Add detected issues to an issues list.
依次执行以下检查，将检测到的问题添加至问题列表。

Check 1: Requirement ID Consistency [CRITICAL]

检查1：需求ID一致性 [CRITICAL]

Purpose: Verify that requirement IDs defined in requirement.md are correctly referenced in design.md and tasks.md.
Procedure:
  1. Extract requirement IDs from requirement.md (regex: 
    \[(REQ|NFR|CON|ASM|T)-\d{3,}\]
    )
  2. Extract referenced requirement IDs from design.md
  3. Extract referenced requirement IDs from tasks.md
Detection patterns:
  • [CRITICAL] ID referenced in design.md or tasks.md but not defined in requirement.md
    ID: CRITICAL-{seq}
Title: "Requirement ID {req_id} does not exist"
File: design.md or tasks.md
Line: {line_number}
Description: "{req_id} is referenced in {file} but not defined in requirement.md"
Suggestion: "Add {req_id} to requirement.md or fix the reference"
  • [INFO] ID defined in requirement.md but never referenced
    ID: INFO-{seq}
Title: "Requirement ID {req_id} is unreferenced"
File: requirement.md
Line: {line_number}
Description: "{req_id} is not linked to any design or task"
Suggestion: "Is this requirement still needed? Consider removing if unnecessary"
  • [WARNING] Insufficient requirement coverage (calculate design.md reference rate for all IDs including [NFR-XXX]; warn if below 100%)
    ID: WARNING-{seq}
Title: "Requirement coverage: {covered}/{total} ({percentage}%)"
Description: "The following requirements are not mentioned in design.md: {uncovered_list}"
Suggestion: "Add coverage for each requirement in design.md"
目的: 验证requirement.md中定义的需求ID在design.md和tasks.md中被正确引用。
流程:
  1. 从requirement.md中提取需求ID（正则表达式：
    \[(REQ|NFR|CON|ASM|T)-\d{3,}\]
    ）
  2. 从design.md中提取被引用的需求ID
  3. 从tasks.md中提取被引用的需求ID
检测模式:
  • [CRITICAL] design.md或tasks.md中引用的ID未在requirement.md中定义
    ID: CRITICAL-{seq}
Title: "Requirement ID {req_id} does not exist"
File: design.md or tasks.md
Line: {line_number}
Description: "{req_id} is referenced in {file} but not defined in requirement.md"
Suggestion: "Add {req_id} to requirement.md or fix the reference"
  • [INFO] requirement.md中定义的ID从未被引用
    ID: INFO-{seq}
Title: "Requirement ID {req_id} is unreferenced"
File: requirement.md
Line: {line_number}
Description: "{req_id} is not linked to any design or task"
Suggestion: "Is this requirement still needed? Consider removing if unnecessary"
  • [WARNING] 需求覆盖不足（计算design.md对所有ID包括[NFR-XXX]的引用率；若低于100%则发出警告）
    ID: WARNING-{seq}
Title: "Requirement coverage: {covered}/{total} ({percentage}%)"
Description: "The following requirements are not mentioned in design.md: {uncovered_list}"
Suggestion: "Add coverage for each requirement in design.md"

Check 2: Required Section Validation [WARNING]

检查2：必填章节验证 [WARNING]

Purpose: Confirm each spec has the expected structure.
Required sections:
  • requirement.md: Overview, Functional Requirements, Non-Functional Requirements, Constraints, Assumptions
  • design.md: Architecture Overview, Technology Stack, Data Model, API Design (if applicable), Security Design
  • tasks.md: Task List, Priority
Procedure:
  1. Extract Markdown headings (
    #
    or 
    ##
    ) from each file
  2. Check for required sections (partial match, case-insensitive)
Detection pattern:
  • [WARNING] Required section missing 
    ID: WARNING-{seq}
Title: "Required section '{section_name}' is missing"
File: {filename}
Line: 1
Description: "{filename} should contain a '{section_name}' section"
Suggestion: "Add a '{section_name}' section"
目的: 确认每个规格文档具备预期结构。
必填章节:
  • requirement.md: 概述、功能需求、非功能需求、约束条件、假设条件
  • design.md: 架构概述、技术栈、数据模型、API设计（如适用）、安全设计
  • tasks.md: 任务列表、优先级
流程:
  1. 从每个文件中提取Markdown标题（
    #
    或 
    ##
    ）
  2. 检查是否包含必填章节（部分匹配，不区分大小写）
检测模式:
  • [WARNING] 缺失必填章节 
    ID: WARNING-{seq}
Title: "Required section '{section_name}' is missing"
File: {filename}
Line: 1
Description: "{filename} should contain a '{section_name}' section"
Suggestion: "Add a '{section_name}' section"

Check 3: Contradiction Detection [WARNING]

检查3：矛盾内容检测 [WARNING]

Purpose: Detect contradictory statements across specification documents.
Detection examples:
  • Technology stack mismatch (e.g., requirement says PostgreSQL, design says MySQL)
  • Numeric mismatch (e.g., requirement says "100 users", design says "1000 users")
  • API endpoint mismatch
  • Components designed in design.md but missing from tasks.md implementation plan
Procedure:
  1. Extract technical proper nouns from requirement.md (database names, library names, etc.)
  2. Check if the same concept is referred to by a different name in design.md
  3. Detect numeric data inconsistencies
Detection pattern:
  • [WARNING] Contradictory statements 
    ID: WARNING-{seq}
Title: "Contradiction: {concept}"
File: requirement.md, design.md
Line: {line_number}
Description: "requirement.md states {value1}, but design.md states {value2}"
Suggestion: "Unify to one value"
目的: 检测规格文档之间的矛盾表述。
检测示例:
  • 技术栈不匹配（例如：需求文档指定PostgreSQL，设计文档使用MySQL）
  • 数值不一致（例如：需求文档说明“100用户”，设计文档说明“1000用户”）
  • API端点不匹配
  • 设计文档中定义的组件在任务文档的实现计划中缺失
流程:
  1. 从requirement.md中提取技术专有名词（数据库名称、库名称等）
  2. 检查同一概念在design.md中是否使用不同名称表述
  3. 检测数值数据不一致
检测模式:
  • [WARNING] 矛盾表述 
    ID: WARNING-{seq}
Title: "Contradiction: {concept}"
File: requirement.md, design.md
Line: {line_number}
Description: "requirement.md states {value1}, but design.md states {value2}"
Suggestion: "Unify to one value"

Check 4: Ambiguous Expression Detection [INFO]

检查4：模糊表达检测 [INFO]

Purpose: Detect vague expressions that lack the specificity needed for implementation.
Detection keywords (English):
  • "appropriately", "as much as possible", "reasonable", "adequate"
  • "fast", "large amount", "many" (without numeric criteria)
  • "to be determined", "under consideration", "planned" (not finalized)
Detection keywords (Japanese):
  • 「適切に」「できる限り」「なるべく」「ある程度」
  • 「高速に」「大量の」「多くの」（数値基準なし）
  • 「検討する」「考慮する」「予定」（確定していない）
Procedure:
  1. Search all three specs for ambiguous keywords
  2. List all occurrences
Detection pattern:
  • [INFO] Ambiguous expression 
    ID: INFO-{seq}
Title: "Ambiguous expression: '{keyword}'"
File: {filename}
Line: {line_number}
Description: "The expression '{context}' may be interpreted differently by implementors"
Suggestion: "Specify concrete numbers or criteria"
目的: 检测缺乏实现所需具体性的模糊表述。
检测关键词（英文）:
  • "appropriately", "as much as possible", "reasonable", "adequate"
  • "fast", "large amount", "many"（无数值标准）
  • "to be determined", "under consideration", "planned"（未最终确定）
检测关键词（日语）:
  • 「適切に」「できる限り」「なるべく」「ある程度」
  • 「高速に」「大量の」「多くの」（数値基準なし）
  • 「検討する」「考慮する」「予定」（確定していない）
流程:
  1. 在三个规格文档中搜索模糊关键词
  2. 列出所有出现位置
检测模式:
  • [INFO] 模糊表达 
    ID: INFO-{seq}
Title: "Ambiguous expression: '{keyword}'"
File: {filename}
Line: {line_number}
Description: "The expression '{context}' may be interpreted differently by implementors"
Suggestion: "Specify concrete numbers or criteria"

Check 5: Terminology Consistency [WARNING]

检查5：术语一致性 [WARNING]

Purpose: Ensure consistent terminology usage across all specifications.
Detection patterns:
  • Same concept expressed with different terms (e.g., "user" vs "member", "delete" vs "remove")
  • Inconsistent abbreviations (e.g., "DB" and "database" mixed)
  • Terms deviating from glossary definitions (if a glossary section exists)
Procedure:
  1. Extract key nouns/concepts from all three specs
  2. Detect synonym/near-synonym pairs
  3. Cross-reference with glossary section if present
Output: 
WARNING-{seq}
"Terminology inconsistency: '{term1}' vs '{term2}'" + recommendation to unify
目的: 确保所有规格文档中术语使用一致。
检测模式:
  • 同一概念使用不同术语表述（例如："user" vs "member"，"delete" vs "remove"）
  • 缩写不一致（例如：混用"DB"和"database"）
  • 术语与词汇表定义不符（若存在词汇表章节）
流程:
  1. 从三个规格文档中提取关键名词/概念
  2. 检测同义词/近义词语对
  3. 若存在词汇表章节则进行交叉引用
输出: 
WARNING-{seq}
"Terminology inconsistency: '{term1}' vs '{term2}'" + 统一术语的建议

Check 6: Design-to-Task Coverage [WARNING]

检查6：设计到任务的覆盖性 [WARNING]

Purpose: Verify that design.md components have corresponding implementation tasks in tasks.md.
Detection patterns:
  • Designed component/module with no corresponding task
  • DB schema design with no migration task
  • API design with no implementation task
Procedure:
  1. Extract major component/module names from design.md
  2. Check if each component has a corresponding task in tasks.md
  3. List uncovered design elements
Output: 
WARNING-{seq}
"Design element '{component}' has no corresponding task"
目的: 验证design.md中的组件在tasks.md中有对应的实现任务。
检测模式:
  • 已设计的组件/模块无对应任务
  • 数据库 Schema 设计无迁移任务
  • API设计无实现任务
流程:
  1. 从design.md中提取主要组件/模块名称
  2. 检查每个组件在tasks.md中是否有对应任务
  3. 列出未覆盖的设计元素
输出: 
WARNING-{seq}
"Design element '{component}' has no corresponding task"

Check 7: Dependency Validation [WARNING]

检查7：依赖关系验证 [WARNING]

Purpose: Verify that task dependencies are logically correct.
Detection patterns:
  • Circular dependencies (Task A depends on B, B depends on A)
  • Undefined prerequisite tasks (dependency on non-existent task)
  • Obviously reversed dependency order (e.g., test task before implementation task)
Procedure:
  1. Extract inter-task dependencies from tasks.md
  2. Build dependency graph and detect cycles
  3. Flag logically inconsistent ordering
Output: 
WARNING-{seq}
"Circular dependency: {taskA} ⇄ {taskB}" or "Illogical dependency order"
目的: 验证任务依赖关系在逻辑上正确。
检测模式:
  • 循环依赖（任务A依赖任务B，任务B依赖任务A）
  • 未定义的前置任务（依赖不存在的任务）
  • 明显颠倒的依赖顺序（例如：测试任务在实现任务之前）
流程:
  1. 从tasks.md中提取任务间的依赖关系
  2. 构建依赖图并检测循环
  3. 标记逻辑不一致的顺序
输出: 
WARNING-{seq}
"Circular dependency: {taskA} ⇄ {taskB}" 或 "Illogical dependency order"

Check 8: Infeasible Requirement Warning [WARNING]

检查8：不可行需求警告 [WARNING]

Purpose: Detect technically difficult or contradictory requirements.
Detection patterns:
  • Conflicting non-functional requirements (e.g., "response under 1ms" + "encrypt all data")
  • Features difficult to achieve with the chosen technology stack
  • Unrealistic resource requirements (e.g., unlimited storage, zero downtime)
Output: 
WARNING-{seq}
"Potentially infeasible: {requirement}" + alternative suggestion
目的: 检测技术上难以实现或自相矛盾的需求。
检测模式:
  • 冲突的非功能需求（例如：“响应时间低于1ms” + “加密所有数据”）
  • 所选技术栈难以实现的功能
  • 不切实际的资源需求（例如：无限存储、零停机时间）
输出: 
WARNING-{seq}
"Potentially infeasible: {requirement}" + 替代方案建议

Check 9: Missing Requirement Detection [WARNING]

检查9：缺失需求检测 [WARNING]

Purpose: Detect clearly necessary but undocumented requirements.
Detection patterns:
  • Authentication present → no security requirements
  • Database used → no backup/recovery requirements
  • External API integration → no error handling/retry requirements
  • File upload → no size/format restrictions
  • User data storage → no privacy/data protection requirements
Procedure:
  1. Extract feature characteristics from requirement.md / design.md
  2. Match against detection patterns and check for corresponding requirements
Output: 
WARNING-{seq}
"Possible missing requirement: {requirement_type} for {feature} is undefined"
目的: 检测明显必要但未记录的需求。
检测模式:
  • 存在认证功能 → 无安全需求
  • 使用数据库 → 无备份/恢复需求
  • 集成外部API → 无错误处理/重试需求
  • 文件上传 → 无大小/格式限制
  • 存储用户数据 → 无隐私/数据保护需求
流程:
  1. 从requirement.md / design.md中提取功能特征
  2. 与检测模式匹配并检查是否有对应需求
输出: 
WARNING-{seq}
"Possible missing requirement: {requirement_type} for {feature} is undefined"

Check 10: Naming Convention Consistency [INFO]

检查10：命名规范一致性 [INFO]

Purpose: Verify consistent naming conventions across specifications.
Detection patterns:
  • Mixed kebab-case / camelCase / snake_case
  • Naming variations in the same context (e.g., 
    user_id
    vs 
    userId
    vs 
    userID
    )
  • Convention violations in constants, table names, component names
Procedure:
  1. Extract code-related names (variable names, table names, API names, etc.) from design.md / tasks.md
  2. Gather naming pattern statistics and flag minority patterns
Output: 
INFO-{seq}
"Naming convention inconsistency: {pattern1} ({count1} occurrences) vs {pattern2} ({count2} occurrences)"
目的: 验证所有规格文档中命名规范一致。
检测模式:
  • 混用kebab-case / camelCase / snake_case
  • 同一上下文中命名不一致（例如：
    user_id
    vs 
    userId
    vs 
    userID
    ）
  • 常量、表名、组件名违反命名规范
流程:
  1. 从design.md / tasks.md中提取代码相关名称（变量名、表名、API名等）
  2. 统计命名模式并标记少数模式
输出: 
INFO-{seq}
"Naming convention inconsistency: {pattern1} ({count1} occurrences) vs {pattern2} ({count2} occurrences)"

Check 11: Directory Structure Consistency [INFO]

检查11：目录结构一致性 [INFO]

Purpose: Verify consistent directory structure and placement rules.
Detection patterns:
  • Inconsistent placement of similar components (e.g., 
    src/features/A/
    vs 
    src/components/B/
    )
  • Mixed test file placement (
    tests/
    vs 
    __tests__/
    )
  • Scattered configuration files
Output: 
INFO-{seq}
"Directory structure inconsistency: {pattern description}"
目的: 验证目录结构和放置规则一致。
检测模式:
  • 相似组件放置不一致（例如：
    src/features/A/
    vs 
    src/components/B/
    ）
  • 测试文件放置混乱（
    tests/
    vs 
    __tests__/
    ）
  • 配置文件分散
输出: 
INFO-{seq}
"Directory structure inconsistency: {pattern description}"

Check 12: Reinvention Detection [INFO]

检查12：重复实现检测 [INFO]

Purpose: Detect custom implementations of functionality already available in declared libraries.
Detection patterns:
  • Reimplementation of features provided by libraries in the technology stack
    • e.g., Custom date handling when date-fns is included
    • e.g., Custom validation when Zod is included
  • Reimplementation of standard library features
Procedure:
  1. Extract library list from the "Technology Stack" section of design.md
  2. Compare against implementation tasks in tasks.md to detect overlapping functionality
Output: 
INFO-{seq}
"Possible reinvention: {task} could be handled by {library_name}"
目的: 检测已在声明库中提供的功能被自定义实现。
检测模式:
  • 重新实现技术栈中库已提供的功能
    • 例如：已包含date-fns却自定义日期处理
    • 例如：已包含Zod却自定义验证逻辑
  • 重新实现标准库功能
流程:
  1. 从design.md的“技术栈”部分提取库列表
  2. 与tasks.md中的实现任务对比，检测功能重叠
输出: 
INFO-{seq}
"Possible reinvention: {task} could be handled by {library_name}"

Check 13: Project Rule Compliance [WARNING]

检查13：项目规则合规性 [WARNING]

Purpose: Check that specifications comply with project-specific rules defined in CLAUDE.md / AGENTS.md and coding-rules.md.
Procedure:
  1. Read 
    CLAUDE.md
    , 
    AGENTS.md
    , and 
    .claude/
    from the project root
  2. Read 
    docs/coding-rules.md
    if it exists (or path from CLAUDE.md/AGENTS.md)
  3. Extract 
    [MUST]
    rules from coding-rules.md
  4. Extract coding conventions, prohibited patterns, and required patterns
  5. Cross-reference with design.md / tasks.md
Detection examples:
  • "TypeScript strict mode required" → not mentioned in design.md
  • "JWT authentication required" → design.md uses a different approach
  • "console.log prohibited" → tasks.md describes console.log usage
coding-rules.md specific checks:
  • Naming rules vs design.md file/class naming (e.g., coding-rules: 
    [MUST] kebab-case
    vs design: 
    UserProfile.service.ts
    )
  • Test coverage requirements vs tasks.md test planning (e.g., coding-rules: 
    [MUST] 80%+ coverage
    vs tasks.md has no test tasks)
  • Required libraries vs design.md technology choices (e.g., coding-rules: 
    [MUST] Use Prisma
    vs design: direct SQL)
  • Prohibited patterns vs design.md/tasks.md descriptions
Output: 
WARNING-{seq}
"Project rule violation: {rule} conflicts with {violation_location}"
目的: 检查规格文档是否符合CLAUDE.md / AGENTS.md和coding-rules.md中定义的项目特定规则。
流程:
  1. 读取项目根目录下的
    CLAUDE.md
    、
    AGENTS.md
    和
    .claude/
  2. 若存在则读取
    docs/coding-rules.md
    （或CLAUDE.md/AGENTS.md中指定的路径）
  3. 从coding-rules.md中提取
    [MUST]
    规则
  4. 提取编码规范、禁止模式和必填模式
  5. 与design.md / tasks.md进行交叉引用
检测示例:
  • "TypeScript strict mode required" → design.md中未提及
  • "JWT authentication required" → design.md使用不同方案
  • "console.log prohibited" → tasks.md描述了console.log的使用
coding-rules.md专项检查:
  • 命名规则与design.md中的文件/类命名对比（例如：编码规则要求
    [MUST] kebab-case
    ，但设计文档使用
    UserProfile.service.ts
    ）
  • 测试覆盖率要求与tasks.md中的测试计划对比（例如：编码规则要求
    [MUST] 80%+ coverage
    ，但tasks.md中无测试任务）
  • 必填库与design.md中的技术选择对比（例如：编码规则要求
    [MUST] Use Prisma
    ，但设计文档使用直接SQL）
  • 禁止模式与design.md/tasks.md中的描述对比
输出: 
WARNING-{seq}
"Project rule violation: {rule} conflicts with {violation_location}"

Check 14: API / UI Naming Convention Consistency [WARNING]

检查14：API / UI命名规范一致性 [WARNING]

Purpose: Validate API and UI naming conventions (for web app / API specifications).
Detection patterns:
  • Inconsistent singular/plural in REST resource names (
    /user/:id
    vs 
    /comments
    )
  • Non-RESTful verb paths (
    /getUsers
    → 
    /users
    (GET) is recommended)
  • Path casing inconsistency (
    /user-profile
    vs 
    /userProfile
    )
  • Path parameter format inconsistency (
    :id
    vs 
    {id}
    )
  • Screen component suffix inconsistency (
    Screen
    vs 
    Page
    )
Procedure:
  1. Extract endpoint list from the "API Design" section of design.md
  2. Extract screen names / routing from tasks.md
  3. Identify majority pattern as "recommended" and flag minority pattern
Output: 
WARNING-{seq}
"API naming inconsistency: {details}" + unification suggestion
目的: 验证API和UI命名规范（针对Web应用/API规格）。
检测模式:
  • REST资源名称单复数不一致（
    /user/:id
    vs 
    /comments
    ）
  • 非RESTful动词路径（
    /getUsers
    → 推荐使用
    /users
    (GET)）
  • 路径大小写不一致（
    /user-profile
    vs 
    /userProfile
    ）
  • 路径参数格式不一致（
    :id
    vs 
    {id}
    ）
  • 屏幕组件后缀不一致（
    Screen
    vs 
    Page
    ）
流程:
  1. 从design.md的“API设计”部分提取端点列表
  2. 从tasks.md中提取屏幕名称/路由
  3. 将多数模式确定为“推荐”并标记少数模式
输出: 
WARNING-{seq}
"API naming inconsistency: {details}" + 统一建议

Check 15: Documentation Update Analysis [INFO]

检查15：文档更新分析 [INFO]

Purpose: Analyze whether existing documentation needs updating based on spec content.
Target documents:
  • README.md, CLAUDE.md, AGENTS.md
  • coding-rules.md (detected path or 
    docs/coding-rules.md
    )
  • issue-to-pr-workflow.md (detected path or 
    docs/issue-to-pr-workflow.md
    )
  • Files in documentation directories specified by CLAUDE.md (e.g., 
    docs/
    )
Procedure:
  1. Check for README.md, CLAUDE.md, AGENTS.md at project root
  2. Parse CLAUDE.md for documentation directory references and scan them
  3. Cross-reference with spec content:
    • New feature → not listed in README.md feature list
    • New API endpoint → not in API docs
    • Technology stack change → setup guide not updated
    • New coding convention → CLAUDE.md / AGENTS.md not updated
    • Shared library or utility changes → coding-rules.md library usage rules may need updating
    • Workflow process changes → issue-to-pr-workflow.md may need updating
    • New quality gates or coding standards → coding-rules.md may need updating
  4. Propose needed updates as DOC-XXX tasks
Output:
  • INFO-{seq}
    "Documentation update needed: {filename} — {reason}"
  • Suggest additions to tasks.md: 
    ### Documentation Update Tasks (auto-detected)
- [ ] DOC-001: Update {section} in {filename} ({reason})
目的: 根据规格文档内容分析现有文档是否需要更新。
目标文档:
  • README.md、CLAUDE.md、AGENTS.md
  • coding-rules.md（检测到的路径或
    docs/coding-rules.md
    ）
  • issue-to-pr-workflow.md（检测到的路径或
    docs/issue-to-pr-workflow.md
    ）
  • CLAUDE.md中指定的文档目录中的文件（例如：
    docs/
    ）
流程:
  1. 检查项目根目录下的README.md、CLAUDE.md、AGENTS.md
  2. 解析CLAUDE.md中的文档目录引用并扫描这些目录
  3. 与规格文档内容交叉引用:
    • 新功能 → 未在README.md功能列表中列出
    • 新API端点 → 未在API文档中提及
    • 技术栈变更 → 安装指南未更新
    • 新编码规范 → CLAUDE.md / AGENTS.md未更新
    • 共享库或工具变更 → coding-rules.md中的库使用规则可能需要更新
    • 工作流程变更 → issue-to-pr-workflow.md可能需要更新
    • 新质量门或编码标准 → coding-rules.md可能需要更新
  4. 提出需要更新的内容作为DOC-XXX任务
输出:
  • INFO-{seq}
    "Documentation update needed: {filename} — {reason}"
  • 建议添加至tasks.md: 
    ### Documentation Update Tasks (auto-detected)
- [ ] DOC-001: Update {section} in {filename} ({reason})

Step 4: Generate Summary

步骤4：生成摘要

Aggregate detected issues by severity:
  • Critical: {count}
  • Warning: {count}
  • Info: {count}
按严重程度汇总检测到的问题：
  • 严重（Critical）: {count}
  • 警告（Warning）: {count}
  • 信息（Info）: {count}

Step 5: Generate Report

步骤5：生成报告

Write a Markdown report to 
.specs/{project-name}/inspection-report.md
.
Template: 
# spec-inspect Report — {project_name}
→ Inspection summary (date, targets, counts) → Severity sections (CRITICAL / WARNING / INFO). Each issue: 
### [{issue.id}] {issue.title}
+ file:line, details, suggestion. Display "None" for sections with 0 issues.
Save with Write tool to 
.specs/{project-name}/inspection-report.md
.
将Markdown报告写入
.specs/{project-name}/inspection-report.md
。
模板: 
# spec-inspect Report — {project_name}
→ 检查摘要（日期、目标、数量）→ 严重程度章节（CRITICAL / WARNING / INFO）。每个问题：
### [{issue.id}] {issue.title}
+ 文件:行号、详情、建议。无问题的章节显示“None”。
使用Write工具保存至
.specs/{project-name}/inspection-report.md
。

Step 6: Console Output

步骤6：控制台输出

Display a user-friendly summary:
spec-inspect complete

Results:
  CRITICAL: {count}
  WARNING:  {count}
  INFO:     {count}

{if critical_count > 0}
Critical issues found. Fix before implementation.

{if critical_count == 0}
No critical issues found.

Report: .specs/{project-name}/inspection-report.md
显示用户友好的摘要：
spec-inspect complete

Results:
  CRITICAL: {count}
  WARNING:  {count}
  INFO:     {count}

{if critical_count > 0}
Critical issues found. Fix before implementation.

{if critical_count == 0}
No critical issues found.

Report: .specs/{project-name}/inspection-report.md

Step 7: Next Action Suggestion (Workflow Integration)

步骤7：下一步操作建议（工作流集成）

Use AskUserQuestion to suggest the next action based on results (header: "Next action" / "次のアクション", multiSelect: false):
ResultQuestionOptions
Critical issues"{count} critical issue(s) found. Action needed." / "Critical問題が{count}件。修正が必要です""Fix and re-run" / "修正して再実行", "Skip to Issue registration" / "スキップしてIssue登録", "Cancel" / "キャンセル"
Warning/Info only"{count} warning(s) found. Proceed to Issue registration?" / "Warningが{count}件。Issue登録しますか？""Register Issue" / "Issue登録する", "Fix and re-run" / "修正して再実行", "Cancel" / "キャンセル"
No issues"Quality check passed. Register Issues?" / "品質チェック完了。Issue登録しますか？""Register Issue" / "Issue登録する", "Cancel" / "キャンセル"
Handling user selection:
  • "Register Issue" / "Skip to Issue registration" → invoke spec-to-issue skill
  • "Fix and re-run" → exit (user fixes and re-runs manually)
  • "Cancel" → exit
使用AskUserQuestion根据结果建议下一步操作（标题："Next action" / "次のアクション"，multiSelect: false）：
结果问题选项
存在严重问题"{count} critical issue(s) found. Action needed." / "Critical問題が{count}件。修正が必要です""Fix and re-run" / "修正して再実行", "Skip to Issue registration" / "スキップしてIssue登録", "Cancel" / "キャンセル"
仅警告/信息"{count} warning(s) found. Proceed to Issue registration?" / "Warningが{count}件。Issue登録しますか？""Register Issue" / "Issue登録する", "Fix and re-run" / "修正して再実行", "Cancel" / "キャンセル"
无问题"Quality check passed. Register Issues?" / "品質チェック完了。Issue登録しますか？""Register Issue" / "Issue登録する", "Cancel" / "キャンセル"
用户选择处理:
  • "Register Issue" / "Skip to Issue registration" → 调用spec-to-issue工具
  • "Fix and re-run" → 退出（用户手动修复后重新运行）
  • "Cancel" → 退出

Step 8: Save Handoff Data for spec-to-issue

步骤8：保存spec-to-issue的交接数据

Save inspection results as a temporary file for the next skill:
json
{
  "project_path": ".specs/{project-name}",
  "project_name": "{project-name}",
  "critical_count": 0,
  "warning_count": 0,
  "info_count": 0,
  "report_path": ".specs/{project-name}/inspection-report.md",
  "timestamp": "{ISO 8601}"
}
Save with Write tool:
Write(".specs/{project-name}/.inspection_result.json", json_content)
将检查结果保存为临时文件供下一个工具使用：
json
{
  "project_path": ".specs/{project-name}",
  "project_name": "{project-name}",
  "critical_count": 0,
  "warning_count": 0,
  "info_count": 0,
  "report_path": ".specs/{project-name}/inspection-report.md",
  "timestamp": "{ISO 8601}"
}
使用Write工具保存：
Write(".specs/{project-name}/.inspection_result.json", json_content)

Error Handling

错误处理

  • File not found: "Error: Required file not found" + missing filename, path verification guidance
  • Read error: "Error: Failed to read file" + filename, error details
  • ID extraction error: Continue processing and display "Warning: Partial error during requirement ID extraction"
  • 文件未找到: "Error: Required file not found" + 缺失文件名、路径验证指引
  • 读取错误: "Error: Failed to read file" + 文件名、错误详情
  • ID提取错误: 继续处理并显示"Warning: Partial error during requirement ID extraction"

Implementation Notes

实现说明

  • Efficiency: Minimize Read operations for large files. Use search tools for efficient scanning. Show progress after each check.
  • Accuracy: Use partial matching for section names. Consider context for contradiction detection. Flexibly match both Japanese and English content.
  • UX: Errors should include concrete, actionable fix suggestions. Use emoji indicators for visual clarity.
  • 效率: 对大文件尽量减少Read操作。使用搜索工具高效扫描。每次检查后显示进度。
  • 准确性: 对章节名称使用部分匹配。矛盾检测需考虑上下文。灵活匹配日语和英语内容。
  • 用户体验: 错误信息应包含具体、可操作的修复建议。使用表情符号增强视觉清晰度。

Constraints

约束条件

  • Supports specifications in both Japanese and English (natural language analysis has inherent accuracy limits)
  • Only Markdown-format specifications are supported
  • Depends on spec-generator output format
  • 支持日语和英语规格文档（自然语言分析存在固有精度限制）
  • 仅支持Markdown格式的规格文档
  • 依赖spec-generator的输出格式

Success Criteria

成功标准

  • Requirement ID reference error detection rate: 100%
  • Missing required section detection rate: 100%
  • Contradiction detection accuracy: Best effort (depends on LLM reasoning capability)
  • Processing time: Under 30 seconds for combined spec files under 3000 lines
  • 需求ID引用错误检测率: 100%
  • 缺失必填章节检测率: 100%
  • 矛盾检测准确性: 尽最大努力（依赖LLM推理能力）
  • 处理时间: 总行数3000行以内的规格文档组合处理时间在30秒以内