spec-inspect

spec-inspect — 仕様品質チェッカー

spec-generator の出力（requirement.md、design.md、tasks.md）を自動的に検証し、品質上の問題を報告します。

言語ルール

1. 入力言語を自動検出 → 同じ言語で出力
2. 日本語の入力 → 日本語でレポートを出力
3. 英語の入力 → 英語でレポートを出力
4. 明示的な指定が優先されます（例：「英語で」、「日本語で」）

実行タイミング

• spec-generator の完了後（自動的に提案されます）
• spec-to-issue で Issue を登録する前
• 仕様書の更新後

実行フロー

Step 1: プロジェクトパスの特定

ユーザー入力または現在のコンテキストから、.specs/{project-name}/ パスを特定します。

検証：

• .specs/{project-name}/requirement.md が存在する
• .specs/{project-name}/design.md が存在する
• .specs/{project-name}/tasks.md が存在する

ファイルが1つでも不足している場合は、エラーメッセージを表示して終了します。

Step 2: 仕様書の読み込み

次の3つの仕様書をすべて読み込みます。

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

仕様書の言語を検出し、現在利用可能なスキルから名前で spec-writing を解決して、その完全な SKILL.md と、対応する references/abstract-verbs.md または references/abstract-verbs.ja.md を主要な語彙ソースとして一度読み込みます。対応する abstract-process-check.md と projection-consistency-check.md のリファレンス（日本語の場合は *.ja.md）を読み込み、Step 3 で両方のチェックを実行します。スキル、語彙、必須列、または ID を読み込めない場合は、パターンリストを推測せずに、abstract-process リファレンスの語彙エラー手順に従います。それ以外のすべてのチェックは続行します。

Step 3: 品質チェックの実行

次のチェックを順番に実行します。検出された問題を issue リストに追加します。

Check 1: 要件 ID の整合性 [CRITICAL]

目的：requirement.md で定義された要件 ID が、存在する場合は design.md、tasks.md、test.md で正しく参照されていることを確認します。

手順：

1. requirement.md から要件 ID を抽出します（正規表現：\\[(REQ|NFR|CON|ASM|T)-\\d{3,}\\]）
2. 存在する場合は design.md、tasks.md、test.md から参照されている要件 ID を抽出します

検出パターン：

• [CRITICAL] design.md、tasks.md、または test.md で参照されているが、requirement.md で定義されていない ID

  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] 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] 要件のカバレッジが不十分（[NFR-XXX] を含むすべての ID について design.md での参照率を計算し、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: 必須構成と要件の境界 [WARNING]

目的：各仕様書に想定されるセクションがあり、スコープの境界が空でなく、要件がテスト可能であることを確認します。

手順：

1. 選択された references/requirement-boundary-check.md / .ja.md を requirement.md に対して実行します。
2. design.md には Architecture Overview、Technology Stack、Data Model、該当する場合は API Design、Security Design を必須とします。tasks.md には Task List と Priority を必須とします。

出力：必須セクションの欠落、選択されたスコープ外セクションが空、または空でない受け入れ基準リストを持たない REQ / NFR ブロックごとに、WARNING-{seq} を1件出力します。

Check 3: 矛盾の検出 [WARNING]

目的：仕様書間の矛盾した記述を検出します。

検出例：

• 技術スタックの不一致（例：要件では PostgreSQL、設計では MySQL）
• 数値の不一致（例：要件では「100 users」、設計では「1000 users」）
• API エンドポイントの不一致
• design.md で設計されているが、tasks.md の実装計画にないコンポーネント

手順：

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]

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"

チェック 10：命名規則の一貫性 [INFO]

目的：仕様全体で命名規則に一貫性があることを確認します。

検出パターン：

• kebab-case／camelCase／snake_case の混在
• 同じ文脈での命名の揺れ（例：user_id と userId と userID）
• 定数、テーブル名、コンポーネント名における規則違反

手順：

1. design.md／tasks.md からコードに関連する名前（変数名、テーブル名、API 名など）を抽出します
2. 命名パターンの統計を集計し、少数派のパターンにフラグを立てます

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

チェック 11：ディレクトリ構造の一貫性 [INFO]

目的：ディレクトリ構造と配置ルールに一貫性があることを確認します。

検出パターン：

• 類似コンポーネントの配置に一貫性がない（例：src/features/A/ と src/components/B/）
• テストファイルの配置が混在している（tests/ と __tests__/）
• 設定ファイルが分散している

出力：INFO-{seq} "Directory structure inconsistency: {pattern description}"

チェック 12：再実装の検出 [INFO]

目的：宣言されているライブラリですでに利用できる機能の独自実装を検出します。

検出パターン：

• 技術スタックのライブラリが提供する機能の再実装
  • 例：date-fns が含まれている場合の日付処理の独自実装
  • 例：Zod が含まれている場合のバリデーションの独自実装
• 標準ライブラリの機能の再実装

手順：

1. design.md の「Technology Stack」セクションからライブラリ一覧を抽出します
2. tasks.md の実装タスクと照合し、機能が重複していないか検出します

出力：INFO-{seq} "Possible reinvention: {task} could be handled by {library_name}"

チェック 13：プロジェクトルールへの準拠 [WARNING]

目的：仕様が 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 モードが必須」→ design.md に記載がない
• 「JWT 認証が必須」→ design.md で異なる方法を採用している
• 「console.log は禁止」→ tasks.md に console.log の使用が記載されている

coding-rules.md 固有のチェック：

• 命名規則と design.md のファイル名／クラス名の照合（例：coding-rules：[MUST] kebab-case と design：UserProfile.service.ts）
• テストカバレッジ要件と tasks.md のテスト計画の照合（例：coding-rules：[MUST] 80%+ coverage に対し、tasks.md にテストタスクがない）
• 必須ライブラリと design.md の技術選定の照合（例：coding-rules：[MUST] Use Prisma に対し、design では直接 SQL を使用）
• 禁止パターンと design.md／tasks.md の記述の照合

出力：WARNING-{seq} "Project rule violation: {rule} conflicts with {violation_location}"

チェック 14：API／UI 命名規則の一貫性 [WARNING]

チェック 14 を開始する前に、 references/extended-quality-checks.md を最後まで読みます（日本語版は .ja.md）。記載されたチェック 14 から 19 を順番に実行し、 各チェックの重要度と出力仕様を変更せずに使用します。

ステップ 4：概要の生成

検出した問題を重要度別に集計します：

• Critical：{count}
• Warning：{count}
• Info：{count}

ステップ 5：レポートの生成

.specs/{project-name}/inspection-report.md に Markdown レポートを書き込みます。

テンプレート：# spec-inspect Report — {project_name} → 検査概要（日付、対象、件数）→ 重要度別セクション（CRITICAL／WARNING／INFO）。各問題：### [{issue.id}] {issue.title} + ファイル：行、詳細、提案。問題が 0 件のセクションには「None」と表示します。

Write ツールを使用して .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