Imported from tuanemuy/dotfiles (agents/skills/implement-audit/SKILL.md). Install upstream with npx skills add tuanemuy/dotfiles --skill implement-audit. Copyright stays with the author.

Implement Audit — 実装完全性の監査レポート

プロジェクト全体の実装を隈なく探査し、未完成コードを検出・レポートする監査専門スキル。

implement スキルファミリーは「省略を残さない」を原則とするが、大量のコード生成の過程で省略が紛れ込むことがある。このスキルは三段構え（パターンマッチング＋コード意味分析＋spec 照合）でスキャンし、構造化レポートを出力する。

このスキルは検出・レポートのみ。修正は行わない。 検出された問題の修正は implement スキルで対象レイヤー・フェーズを再実行するか、個別の implement-* サブスキルで対応する。

Workflow

Phase 1: 対象スコープの決定
  ユーザー指定 or プロジェクト全体

Phase 2: スキャン（検出）
  2a. パターンマッチング — Grep で機械的に検出
  2b. コード意味分析 — サブエージェントで深い検出
  2c. spec 照合 — 設計で定義された要素が実装に存在するか照合

Phase 3: レポート生成
  .audit/completeness/ に構造化レポートを出力

Phase 4: 結果報告・後片付け
  検出結果のサマリーと推奨アクションをユーザーに報告
  検出ゼロなら .audit/completeness/ を削除

Phase 1: 対象スコープの決定

ユーザーが対象ディレクトリやファイルを指定している場合はそれに従う。

指定がない場合は プロジェクト全体を対象にする。 CLAUDE.md からソースディレクトリを読み取り、すべてのソースコードをスキャン対象とする。diff や変更履歴に依存せず、コードベース全体を隈なく探査することがこのスキルの価値。

対象スコープをユーザーに報告してから Phase 2 に進む。

Phase 2: スキャン（検出）

三段構えで未完成箇所を検出する。2a・2b・2c は並列実行してよい。

Phase 2a: パターンマッチングスキャン

対象スコープに対して、references/detection-patterns.md に定義されたパターンで検索する。機械的な検索なのでサブエージェント（探索区分）に委譲する。

検出カテゴリ:

1. 明示的マーカー — TODO, FIXME, HACK, XXX, TEMP, PLACEHOLDER 等のコメント
2. 未実装シグナル — throw new Error("not implemented"), pass, unimplemented!(), 空の関数ボディ等
3. 省略シグナル — // ..., /* ... */, コメントで「省略」「ここに〜を追加」等
4. 仮実装シグナル — ハードコードされた値、dummy, stub, mock（テスト以外）等
5. 不完全な制御フロー — 空の catch、エラー握り潰し、未処理の分岐等

各検出結果について、ファイルパス・行番号・該当行・カテゴリ・所属レイヤーを記録する。

偽陽性フィルタリング

以下は除外する:

• テストファイル内の mock, stub, dummy（テストでは正当）
• ライブラリ・依存パッケージ（node_modules, vendor, .next 等）
• 生成ファイル（.generated., *.g.dart 等）
• ロックファイル（package-lock.json, yarn.lock 等）
• CLAUDE.md や spec/ 内のドキュメント

Phase 2b: コード意味分析（深い検出）

パターンマッチングだけでは検出できない、意味的に省略された箇所を分析する。サブエージェント（審査区分 — 意図的な設計と省略の区別を伴う）を起動し、対象ファイル群を読ませる。

対象ファイル数が多い場合はドメインやディレクトリ単位でサブエージェントを分割して並列実行する。

あなたは実装の完全性を検証する監査エンジニアです。

## 前提
- まずプロジェクトルートの CLAUDE.md を読み、プロジェクトの構成・規約を把握する

## やること
1. 対象ファイルを Read で読む
2. 以下の観点で未完成・省略箇所を探す

## 検出観点
- 関数/メソッドが宣言されているが中身が空または最小限（return null, return undefined, return {} 等）
- エラーハンドリングが省略されている箇所（空の catch、エラーを握り潰している等）
- コメントで「ここに〜を追加」「〜する予定」等と書かれている箇所
- インターフェースやポートが定義されているが、対応する実装が見つからない箇所
- switch/if-else で一部のケースだけ実装され、残りが未処理
- 設定値やマジックナンバーがハードコードされている（設計上外部化すべきもの）
- AI が生成しがちな省略パターン（「// 残りのケースも同様に処理」等のコメントだけで実コードがない）

## 重要
- 偽陽性を避けるために、コンテキストを十分に理解してから判定する
- 意図的な設計（例: 空のインターフェース実装が正しい場合）と省略を区別する
- 判断に迷う場合は「要確認」として記録する

## 出力
各検出項目について:
- ファイルパス:行番号
- カテゴリ（未実装/省略/仮実装/不完全な制御フロー/要確認）
- 確信度（高/中/低）
- 該当コードの抜粋
- なぜ問題と判断したかの根拠
- 所属レイヤー（domain/adapter/usecase/test/frontend/other）

Phase 2c: spec との照合

設計ドキュメントで定義された要素が実装に存在するかを照合する。spec/ が存在しない場合（issue-implement 等で spec を使わないケース）は、.thread/{番号}/plan.md の受け入れ基準に基づいて照合する。どちらも存在しない場合はスキップし、その旨をレポートに記載する。

台帳 spec/inventory/{layer}.md（../_shared/references/spec-inventory.md）が存在する場合は、照合対象の列挙を台帳から取る。各サブエージェントには spec ディレクトリの代わりに担当レイヤーの台帳行を渡し、「各行が実装に存在しスタブでないか」を判定させる（自前で要素を列挙させない）。台帳がない場合のみ、以下のプロンプトのとおり spec から直接列挙させる。

照合対象ごとにサブエージェント（審査区分）を並列起動する。{やること} を差し替えて渡す:

あなたは設計と実装の整合性を検証するエンジニアです。

## 前提
- まずプロジェクトルートの CLAUDE.md を読み、ディレクトリ構成を把握する

## やること
{各照合の「やること」}

## 出力
各未実装要素について:
- 設計上の定義場所（spec のファイルパスとセクション）
- 期待される実装の概要
- 実装が見つからない根拠（Grep した結果等）

ドメイン照合

1. spec/domains/ の各ドメイン設計を読む
2. 各エンティティ・値オブジェクト・ドメインサービス・ポートインターフェースが実装に存在するか Grep/Glob で確認する
3. 設計で定義されたメソッドやプロパティが実装されているかも確認する
4. 設計に存在するが実装が見つからない要素をリストアップする

ユースケース照合

1. spec/usecases/ の各ユースケース設計を読む
2. 各ユースケースの関数・メソッドが実装に存在するか確認する
3. 入出力の型が設計通りか確認する
4. 設計に存在するが実装が見つからない要素をリストアップする

フロントエンド照合（spec/pages/ が存在する場合）

1. spec/pages/ のページ設計を読む
2. 各ページ・コンポーネントが実装に存在するか確認する
3. 設計で定義された画面要素（フォーム、テーブル、ボタン等）が実装されているか確認する
4. フロントエンドからバックエンドへのAPI接続が完全に実装されているか確認する:
   • データ取得・作成・更新・削除の各操作が実際のバックエンドAPIエンドポイントにリクエストを送っているか
   • ダミーデータを返すスタブ関数（例: return [], return {}, ハードコードされた配列やオブジェクト）が本番コードに残っていないか
   • APIクライアント・データ取得関数が実際のHTTPリクエスト（fetch, axios, Server Actions等）を行う実装になっているか
   • バックエンドのAPIルート定義・ハンドラー実装と突き合わせて、フロントエンドが呼んでいるパスやメソッドが正しいか確認する
5. 設計に存在するが実装が見つからない要素をリストアップする

API接続の問題は、上記の出力に加えて「問題の種類（スタブ関数/ダミーデータ/未接続/パス不一致）」と「対応するバックエンドエンドポイント（存在する場合）」も報告させる。

永続化照合（spec/domains/ にポート定義が存在する場合）

1. spec/domains/ のポート定義（メソッドシグネチャ＋振る舞いの契約）を読む
2. 各ポートメソッドに対応するアダプター実装が存在するか、バックエンドごとに確認する
3. spec/testcases/ports/ の適合テストが実装され、各バックエンドに対して実行されているか確認する
4. 設計に存在するが実装が見つからない要素をリストアップする

物理スキーマ（テーブル定義・マイグレーション）は spec の要素ではないため照合対象にしない。ポート契約を満たしているかだけを見る。

Phase 3: レポート生成

生成の前に既存の .audit/completeness/ を削除し、今回の結果だけを置く（過去の監査結果との混在を防ぐ）。全スキャン結果を統合し、.audit/completeness/report.md に出力する。

各検出項目にはレイヤー（domain/adapter/usecase/test/frontend/other）を付与し、修正時にどのレイヤーを再実装すべきか判断できるようにする。

# Implement Audit Report

**Date:** {日時}
**Scope:** {対象ディレクトリ/ファイル}
**Total findings:** {検出数}

---

## レイヤー別サマリー

| レイヤー | Critical | Warning | Info | 合計 |
|---------|----------|---------|------|------|
| domain | {数} | {数} | {数} | {数} |
| adapter | {数} | {数} | {数} | {数} |
| usecase | {数} | {数} | {数} | {数} |
| test | {数} | {数} | {数} | {数} |
| frontend | {数} | {数} | {数} | {数} |
| other | {数} | {数} | {数} | {数} |

## カテゴリ別サマリー

| カテゴリ | 件数 | Critical | Warning | Info |
|---------|------|----------|---------|------|
| 明示的マーカー | {数} | {数} | {数} | {数} |
| 未実装シグナル | {数} | {数} | {数} | {数} |
| 省略シグナル | {数} | {数} | {数} | {数} |
| 仮実装シグナル | {数} | {数} | {数} | {数} |
| 不完全な制御フロー | {数} | {数} | {数} | {数} |
| spec 未実装 | {数} | {数} | {数} | {数} |

---

## Critical（対応必須）

### [C-001] {概要}
- **レイヤー:** {domain/adapter/usecase/test/frontend/other}
- **ファイル:** `{パス}:{行番号}`
- **カテゴリ:** {カテゴリ}
- **コード:**

{該当コード}

- **根拠:** {なぜ問題か}
- **推奨対応:** {どう直すべきか}

---

## Warning（対応推奨）

### [W-001] {概要}
- **レイヤー:** {domain/adapter/usecase/test/frontend/other}
- **ファイル:** `{パス}:{行番号}`
- **カテゴリ:** {カテゴリ}
- **コード:**

{該当コード}

- **根拠:** {なぜ気になるか}
- **推奨対応:** {改善案}

---

## Info（要確認）

### [I-001] {概要}
- **レイヤー:** {domain/adapter/usecase/test/frontend/other}
- **ファイル:** `{パス}:{行番号}`
- **カテゴリ:** {カテゴリ}
- **根拠:** {確認が必要な理由}

---

## spec 照合結果

### 未実装要素

| # | レイヤー | 設計場所 | 要素 | 備考 |
|---|---------|---------|------|------|
| 1 | domain | spec/domains/xxx.md#エンティティ | {要素名} | {実装が見つからない根拠} |

### 照合スキップ
- {照合できなかった箇所とその理由}

---

## 推奨アクション

検出結果に基づき、以下のレイヤーの再実装を推奨する:

| 優先度 | レイヤー | 理由 | 推奨スキル |
|--------|---------|------|-----------|
| 1 | {layer} | Critical {数}件 | implement（Phase {N} を指定）or implement-{layer} |

重要度の分類基準

• Critical — 明らかに実装が欠けている。TODO/FIXME が残っている。spec に定義された要素が実装されていない
• Warning — 仮実装の可能性がある。エラーハンドリングが省略されている。空の関数ボディがある
• Info — 意図的かもしれないが確認が必要。確信度が低い検出

Phase 4: 結果報告・後片付け

レポート生成が完了したら、検出結果のサマリーをユーザーに報告する。

レポートの後片付けは検出結果で分岐する:

• 検出ゼロ（Critical / Warning / Info すべて0件）— .audit/completeness/ を削除し、報告にその旨を記す。クリーンな結果の証明にレポートは要らない
• 検出あり — レポートを残す。修正（implement / implement-* の再実行）の入力になるため。修正が決着したらレポートは削除してよい（implement の Phase 8 経由で呼ばれた場合は、監査が収束した時点でオーケストレーターが削除する）

実装監査が完了しました！

## 結果
- 検出数: Critical {数}件 / Warning {数}件 / Info {数}件

## レイヤー別
{レイヤー別サマリーテーブル}

## レポート
- {.audit/completeness/report.md / 検出ゼロのため削除済み}

## 推奨アクション
{Critical・Warning が検出されたレイヤーについて、再実装の推奨}

例:
- domain レイヤー: Critical 2件 → `implement` で Phase 2（ドメイン実装）を再実行
- frontend レイヤー: Warning 3件 → `implement` で Phase 6（フロントエンド実装）を再実行

原則

• 隈なく探す — 検出漏れはこのスキルの価値を損なう。偽陽性は後から除外できるが、偽陰性は見逃しになる
• プロジェクト全体を対象にする — diff や変更履歴に依存せず、コードベース全体を隈なく探査する
• コンテキストを理解する — テストコード内の mock やスタブは正当。プロダクションコード内の mock は問題
• 三段構えで検出する — パターンマッチング → コード意味分析 → spec 照合。それぞれ検出できるものが違う
• spec 照合は必ず行う — 設計と実装の突き合わせは最も信頼性の高い検出手段。spec も plan.md もない場合のみスキップ
• 検出・レポートに専念する — 修正は行わない。修正は implement スキルや個別サブスキルの役割
• レイヤーを明示する — 各検出項目にレイヤーを付与し、再実装時にどのフェーズを再実行すべきか判断できるようにする
• レポートは構造化する — 後から機械的に処理できるように、一貫したフォーマットで出力する
• レポートは未対応の検出を追跡する間だけ残す — 検出ゼロなら即削除、検出ありでも修正が決着したら削除する。生成時は必ず前回のレポートを消してから作る
• 委譲方式・並列実行・中断時の再委譲・委譲時のコンテキストは ../_shared/references/subagent-policy.md に従う