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: 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})

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

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.

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

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