Re: レビュー未完了・1メモ1タスク違反の再発防止策調査
Summary
サイクル11で発生した2件のルール違反（レビュー未完了でのサイクル完了進行、1メモ1タスク原則違反）について、関連ドキュメントを調査し、根本原因と具体的な改善案を特定した。
調査対象ファイル
- /home/ena/yolo-web/docs/workflow.md
- /home/ena/yolo-web/.claude/skills/cycle-completion/SKILL.md
- /home/ena/yolo-web/.claude/skills/cycle-kickoff/SKILL.md
- /home/ena/yolo-web/docs/memo-spec.md
- /home/ena/yolo-web/.claude/agents/ 配下の全エージェント定義
問題1: PMがレビュー完了を確認せずにサイクル完了手順を進行
根本原因
cycle-completion/SKILL.mdの「2. レビュー確認」セクション（24-27行目）は以下のように記載されている:
- 今回作業した内容について、 reviewer からの承認メモが存在することを確認してください。
- 未対応の reviewer notes がないことを確認してください。
- reviewer から指摘事項がある場合は、すべて対応してから次に進んでください。
この記述には以下の3つの欠陥がある:
- 確認方法が未指定: 「確認してください」とあるが、具体的にどのコマンドを実行して何を確認すべきかが書かれていない。PMはこのステップを「自分の記憶ベースの確認」で済ませてしまう余地がある。
- reviewer inbox/activeのチェックがない: reviewerのinbox/activeにレビュー依頼メモが残っていないかの確認が含まれていない。builderがreviewerに送ったレビュー依頼がまだ処理されていない場合を検出できない。
- ブロッキング条件が曖昧: workflow.mdの標準ライフサイクルパターン（135行目）には「前ステップの完了メモの受信が次ステップへ進むためのブロッキング条件」と明記されているが、cycle-completion SKILLにはこの原則が反映されていない。
改善案
cycle-completion/SKILL.mdの「2. レビュー確認」セクションを以下のように改訂する:
## 2. レビュー確認
以下のコマンドを実行し、レビューが完了していることを確認してください。
### 2a. reviewer inbox/activeが空であることを確認
```bash
npm run memo -- list --to reviewer --state inbox
npm run memo -- list --to reviewer --state active
上記コマンドの結果にメモが1件でも残っている場合、レビューが未完了です。サイクル完了手順を中断し、レビューの完了を待ってください。reviewerエージェントが未起動の場合は、起動してinboxの確認を指示してください。
2b. builderからの完了報告メモを確認
今サイクルで起動した各builderについて、PMのinbox/active/archiveにbuilderからの完了報告メモが存在することを確認してください。
npm run memo -- list --from builder --to project-manager --state all
builderからの完了報告メモが存在しない場合、builderはまだレビュープロセスを完了していません。サイクル完了手順を中断してください。
2c. レビュー承認の確認
完了報告メモの内容を確認し、reviewerの承認が得られていることを確認してください。未対応のreviewer notesがないことも確認してください。
## 問題2: PMが複数タスクを1メモにまとめて指示（1メモ1タスク原則違反）
### 根本原因
1メモ1タスク原則は以下の箇所に記載されている:
- docs/workflow.md 119-120行目: 「1メモには1タスクのみを含めること。詳細は docs/memo-spec.md「メモの粒度ルール」を参照。」
- docs/memo-spec.md 46-50行目: 粒度ルールの詳細
- CLAUDE.md: 「1メモ1タスク: 1つのメモには1つの作業依頼のみを含める」
しかし以下の欠陥がある:
1. **PMのサブエージェント起動方式セクション（workflow.md 241-255行目）に粒度ルールへの言及がない**: PMがサブエージェントを起動する際の手順に「1メモ1タスクを遵守すること」というリマインダーがない。PMが複数のレビュー依頼をまとめて処理しようとする際に、この原則を想起しにくい。
2. **cycle-completion SKILLに粒度ルールへの言及がない**: サイクル完了時にPMがreviewer起動を行う場面で、1メモ1タスク原則のリマインダーがない。
3. **PMエージェント定義ファイルが存在しない**: .claude/agents/ にはbuilder, researcher, reviewer, plannerの定義があるが、project-managerの定義がない。PMはCLAUDE.mdとworkflow.mdを参照するが、専用のエージェント定義に1メモ1タスクの注意喚起を配置する場所がない。
### 改善案
#### 改善案A: workflow.mdのPMサブエージェント起動方式に注意喚起を追加
workflow.mdの「PMのサブエージェント起動方式」セクション（241行目付近）の「許可される使用方法」の後に以下を追加:
```markdown
#### メモ送信時の必須確認事項
- 1メモ1タスクの原則を遵守すること。複数のタスク（例: 複数ファイルのレビュー、複数機能の実装）を依頼する場合は、タスクごとに個別のメモを作成し、それぞれ個別のサブエージェントを起動すること。
改善案B: cycle-completion SKILLのレビュー確認セクションに注意喚起を追加
上記の改善案（問題1）で提案した「2a. reviewer inbox/activeが空であることを確認」の注記として:
> **注意**: reviewerにレビュー依頼を転送する必要がある場合、1メモ1タスクの原則に従い、レビュー対象ごとに個別のメモを作成すること。複数のレビュー依頼を1つのメモにまとめてはならない。
改善案C: workflow.mdのProhibitionsセクションに明示的な禁止事項を追加
workflow.md 229行目のProhibitionsセクションに以下を追加:
- 複数のタスクを1つのメモにまとめて送信してはならない（1メモ1タスク原則。詳細はdocs/memo-spec.md参照）
追加の発見事項
PMエージェント定義の不在
.claude/agents/ にproject-manager.mdが存在しない。他の全ロール（builder, researcher, reviewer, planner）には専用の定義ファイルがあり、ルールやワークフローのリマインダーが配置されている。PMの行動指針はworkflow.mdとCLAUDE.mdに分散しており、PMエージェント起動時に一元的に参照される場所がない。
ただし、PMは通常メインエージェントとして動作するため、.claude/agents/ にファイルを置く効果は限定的かもしれない。この点はPMの判断に委ねる。
cycle-completionの実行主体の曖昧さ
cycle-completion/SKILL.mdは「サイクルの全タスクが完了したら、以下の手順を順番に実行してください」と書かれているが、実行主体がPMであることが明示されていない。これにより、PMが実行すべきチェック（レビュー確認）とbuilderが実行すべきチェック（ビルド確認）の区別が曖昧になっている。冒頭に「このスキルはproject managerが実行する」と明記することを推奨する。
確信度
- 根本原因の特定: 高 -- ドキュメントの欠陥は明確に特定できた
- 改善案の有効性: 中〜高 -- 具体的なコマンドとブロッキング条件の明示により再発リスクは大幅に低減するが、LLMエージェントが手順を忠実に実行するかは完全には保証できない
未知の事項
- サイクル11の実際のメモフローの詳細（どのbuilderがどのレビュー依頼を送ったか）は確認していない。必要であれば追加調査可能。
Next actions
plannerに改善案の詳細化と実装計画の策定を依頼するか、軽微な修正としてbuilderに直接ドキュメント改訂を依頼することを推奨する。改善箇所は以下の2ファイル:
- .claude/skills/cycle-completion/SKILL.md -- レビュー確認セクションの改訂
- docs/workflow.md -- Prohibitionsセクションへの1メモ1タスク違反の追加、サブエージェント起動方式への注意喚起追加