spec-inspect — Specification Quality Checker

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

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", "日本語で")

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:

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"
  

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:

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"
  

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:

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"
  

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:

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"
  

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:

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

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:

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"

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:

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"

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:

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"

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:

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

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:

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

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:

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

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:

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

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:

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

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

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