spec-inspect — Specification Quality Checker

Automatically validates spec-generator output (requirement.md, design.md, tasks.md) and reports quality issues.

Language Rules

Auto-detect input language → output in the same language
Japanese input → Japanese report output
English input → English report output
Explicit override takes priority (e.g., "in English", "日本語で")

When to Run

After spec-generator completes (auto-suggested)
Before registering Issues with spec-to-issue
After updating specification documents

Execution Flow

Step 1: Locate Project Path

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.

Step 2: Read Specifications

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

# Optional: acceptance test plan (only present for full-workflow / pipeline specs).
# Absence is expected for legacy three-document specs — do NOT treat as an error.
test_content = Read(".specs/{project-name}/test.md") or None

# Optional: load coding rules if available
coding_rules = Read("docs/coding-rules.md") or None
# Also check CLAUDE.md / AGENTS.md for alternative path

Step 3: Run Quality Checks

Execute the following checks sequentially. Add detected issues to an issues list.

Check 1: Requirement ID Consistency [CRITICAL]

Purpose: Verify that requirement IDs defined in requirement.md are correctly referenced in design.md and tasks.md.

Procedure:

Extract requirement IDs from requirement.md (regex: \[(REQ|NFR|CON|ASM|T)-\d{3,}\])
Extract referenced requirement IDs from design.md
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"

Check 2: Required Section Validation [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:

Extract Markdown headings (# or ##) from each file
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"

Check 3: Contradiction Detection [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:

Extract technical proper nouns from requirement.md (database names, library names, etc.)
Check if the same concept is referred to by a different name in design.md
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"

Check 4: Ambiguous Expression Detection [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:

Search all three specs for ambiguous keywords
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"

Check 5: Terminology Consistency [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:

Extract key nouns/concepts from all three specs
Detect synonym/near-synonym pairs
Cross-reference with glossary section if present

Output: WARNING-{seq} "Terminology inconsistency: '{term1}' vs '{term2}'" + recommendation to unify

Check 6: Design-to-Task Coverage [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:

Extract major component/module names from design.md
Check if each component has a corresponding task in tasks.md
List uncovered design elements

Output: WARNING-{seq} "Design element '{component}' has no corresponding task"

Check 7: Dependency Validation [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:

Extract inter-task dependencies from tasks.md
Build dependency graph and detect cycles
Flag logically inconsistent ordering

Output: WARNING-{seq} "Circular dependency: {taskA} ⇄ {taskB}" or "Illogical dependency order"

Check 8: Infeasible Requirement Warning [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

Check 9: Missing Requirement Detection [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:

Extract feature characteristics from requirement.md / design.md
Match against detection patterns and check for corresponding requirements

Output: WARNING-{seq} "Possible missing requirement: {requirement_type} for {feature} is undefined"

Check 10: Naming Convention Consistency [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:

Extract code-related names (variable names, table names, API names, etc.) from design.md / tasks.md
Gather naming pattern statistics and flag minority patterns

Output: INFO-{seq} "Naming convention inconsistency: {pattern1} ({count1} occurrences) vs {pattern2} ({count2} occurrences)"

Check 11: Directory Structure Consistency [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}"

Check 12: Reinvention Detection [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:

Extract library list from the "Technology Stack" section of design.md
Compare against implementation tasks in tasks.md to detect overlapping functionality

Output: INFO-{seq} "Possible reinvention: {task} could be handled by {library_name}"

Check 13: Project Rule Compliance [WARNING]

Purpose: Check that specifications comply with project-specific rules defined in CLAUDE.md / AGENTS.md and coding-rules.md.

Procedure:

Read CLAUDE.md, AGENTS.md, and .claude/ from the project root
Read docs/coding-rules.md if it exists (or path from CLAUDE.md/AGENTS.md)
Extract [MUST] rules from coding-rules.md
Extract coding conventions, prohibited patterns, and required patterns
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}"

Check 14: API / UI Naming Convention Consistency [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:

Extract endpoint list from the "API Design" section of design.md
Extract screen names / routing from tasks.md
Identify majority pattern as "recommended" and flag minority pattern

Output: WARNING-{seq} "API naming inconsistency: {details}" + unification suggestion

Check 15: Documentation Update Analysis [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:

Check for README.md, CLAUDE.md, AGENTS.md at project root
Parse CLAUDE.md for documentation directory references and scan them
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
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})

Check 16: Acceptance Test Coverage (test.md) [WARNING]

Purpose: Verify the acceptance test plan (test.md) exists and covers every requirement. test.md is produced by the spec-generator full workflow and consumed by acceptance evaluation. Legacy three-document specs (created before test.md existed) stay valid — its absence is reported as INFO, never as an error, so this check never breaks existing specs.

Test case format (defined by spec-generator, in skills/spec-generator/references/test-plan.md): each case heading is ## T-A{nn}: [REQ-XXX] ..., followed by a verification method field Verify: (Japanese: 検証方法:) valued playwright / command / file-check.

Procedure:

If test_content is None (test.md absent) → emit one INFO finding (see below) and skip steps 2–4. Do not fail; legacy specs remain valid.
Extract test case IDs (T-A\d+) and, per case heading, the requirement IDs referenced (\[(REQ|NFR)-\d+\]).
Extract all REQ / NFR IDs from requirement.md; each with no referencing test case → coverage gap.
Each test case whose Verify: / 検証方法: field is empty, missing, or not one of playwright / command / file-check → verification gap.

Outputs (existing findings format):

[INFO] test.md absent: INFO-{seq} "Acceptance test plan (test.md) not found" — File: test.md. "Acceptance coverage was not checked; run the spec-generator full workflow to generate test.md, or ignore for a three-document-only spec."
[WARNING] uncovered requirements: WARNING-{seq} "Acceptance coverage: {covered}/{total} requirements have a test case" + list of REQ/NFR IDs with no T-A case + "Add a T-A case referencing each."
[WARNING] empty verification method: WARNING-{seq} "Test case {case_id} has no verification method" + "Set Verify (検証方法) to playwright / command / file-check."

Check 17: Referenced Path Existence and Mode [CRITICAL]

Purpose: A spec is unimplementable when a path it tells the implementation to read is untracked, or is a symlink that git tree resolution will not follow.

Procedure:

Extract repo-relative paths the specs use as a content source (a step reads, parses, or diffs the file — not paths cited as examples or outputs).
For each, run git ls-files -s -- <path>: no output = untracked (the read fails on a clean checkout); mode 120000 = symlink (git show HEAD:<path> yields the link target string, not the target's content).
Plain working-tree reads tolerate symlinks; flag mode 120000 when the read goes through git object/tree access or the read side is unspecified.

Outputs:

[CRITICAL] CRITICAL-{seq} "Referenced path {path} is not tracked by git" + "Track the file, or point the spec at the real tracked path"
[CRITICAL] CRITICAL-{seq} "Referenced path {path} is a symlink (mode 120000) used as a content source" + "Point the spec at the symlink's target (the real file path)"

Step 4: Generate Summary

Aggregate detected issues by severity:

Critical: {count}
Warning: {count}
Info: {count}

Step 5: Generate Report

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.

Step 6: Console Output

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

Step 7: Next Action Suggestion (Workflow Integration)

Use AskUserQuestion to suggest the next action based on results (header: "Next action" / "次のアクション", multiSelect: false):

| Result | Question | Options | |--------|----------|---------| | 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

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

Save inspection results as a temporary file for the next skill:

{
  "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)

Error Handling

File not found / read error: "Error: Required file not found" or "Error: Failed to read file" + filename and details, with path verification guidance
ID extraction error: Continue processing and display "Warning: Partial error during requirement ID extraction"

Implementation Notes

Efficiency: Minimize Read operations for large files; use search tools; show progress after each check.
Accuracy / UX: Use partial matching for section names, consider context for contradiction detection, match Japanese and English content flexibly; errors carry concrete fix suggestions with emoji indicators.

Constraints

Supports Markdown specifications in Japanese and English only (natural language analysis has inherent accuracy limits); depends on spec-generator output format

Success Criteria

Requirement ID reference errors, missing required sections, and uncovered REQ/NFR (when test.md is present) detected at 100%; test.md absence reported as INFO without failing legacy specs
Contradiction detection accuracy: Best effort (depends on LLM reasoning capability)
Processing time: Under 30 seconds for combined spec files under 3000 lines