spec-inspect

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

Detect the specification language, resolve spec-writing by name from the currently available skills, and read its complete SKILL.md plus the matching references/abstract-verbs.md or references/abstract-verbs.ja.md once as the primary vocabulary source. Read the matching abstract-process-check.md and projection-consistency-check.md references (*.ja.md for Japanese), and run both checks in Step 3. If the skill, vocabulary, required columns, or IDs cannot be read, follow the abstract-process reference's vocabulary-error procedure without inferring a pattern list; all other checks must continue.

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, tasks.md, and test.md when present.

Procedure:

Extract requirement IDs from requirement.md (regex: \[(REQ|NFR|CON|ASM|T)-\d{3,}\])
Extract referenced requirement IDs from design.md, tasks.md, and test.md when present

Detection patterns:

[CRITICAL] ID referenced in design.md, tasks.md, or test.md but not defined in requirement.md

ID: CRITICAL-{seq}
Title: "Requirement ID {req_id} does not exist"
File: design.md, tasks.md, or test.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 Structure and Requirement Boundaries [WARNING]

Purpose: Confirm each spec has the expected sections, a non-empty scope boundary, and testable requirements.

Procedure:

Run the selected references/requirement-boundary-check.md / .ja.md against requirement.md.
For design.md, require Architecture Overview, Technology Stack, Data Model, API Design when applicable, and Security Design. For tasks.md, require Task List and Priority.

Output: One WARNING-{seq} per missing required section, empty selected out-of-scope section, or REQ / NFR block without a non-empty acceptance-criteria list.

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

"appropriately", "as much as possible", "as far as possible", "to some extent"
"at high speed", "a large amount of", "many" (no numerical criteria)
"consider", "take into account", "plan to" (not yet finalized)

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]

Before starting Check 14, read references/extended-quality-checks.md completely (.ja.md for Japanese). Execute its Checks 14 through 19 in order and use each check's severity and output contract without modification.

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

About this skill

Language Rules

When to Run

Execution Flow

Step 1: Locate Project Path

Step 2: Read Specifications

Step 3: Run Quality Checks

Check 1: Requirement ID Consistency [CRITICAL]

Check 2: Required Structure and Requirement Boundaries [WARNING]

Check 3: Contradiction Detection [WARNING]

Check 4: Ambiguous Expression Detection [INFO]

Check 5: Terminology Consistency [WARNING]

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

Check 7: Dependency Validation [WARNING]

Check 8: Infeasible Requirement Warning [WARNING]

Check 9: Missing Requirement Detection [WARNING]

Check 10: Naming Convention Consistency [INFO]

Check 11: Directory Structure Consistency [INFO]

Check 12: Reinvention Detection [INFO]

Check 13: Project Rule Compliance [WARNING]

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

Step 4: Generate Summary

Step 5: Generate Report

Step 6: Console Output

Step 7: Next Action Suggestion (Workflow Integration)

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

Error Handling

Implementation Notes

Constraints

Success Criteria