ryryo fix-plan — 計画書ファイルのフォーマット修復（v2 対応）
docs/PLAN 配下の tasks.json (schemaVersion 2) に生じた
フォーマット不整合や値の不備を検出・修正するスキル。
v1 (spec.md マークダウンパース) は対象外。
トリガー
/dev:fix-plan- 「計画書が壊れた」「プランの修正」「計画書のフォーマット直す」
- 「ダッシュボードにプランが表示されない」
スクリプト一覧
| スクリプト | 役割 | 実行コマンド |
|---|---|---|
scripts/validate-tasks-json.mjs |
構造 + 整合性の 20 項目チェック。タイポ検出付き | node scripts/validate-tasks-json.mjs <tasks.json> |
scripts/fix-tasks-json.mjs |
progress / status / metadata の自動修復。--dry-run で確認のみ |
node scripts/fix-tasks-json.mjs <tasks.json> [--dry-run] |
scripts/simulate-dashboard-parse.mjs |
ダッシュボードと同じパーサー (plan-json-loader.ts) をローカル実行 | npx tsx scripts/simulate-dashboard-parse.mjs <plan-dir> |
scripts/check-spec-sync.mjs |
spec.md の generated 領域と tasks.json の差分検出 | node scripts/check-spec-sync.mjs <tasks.json> |
エージェント
| ファイル | 役割 |
|---|---|
agents/dashboard-visibility-debug.md |
スクリプトで解決しなかった場合の LLM による原因調査手順 |
実行フロー
Step 1: 対象プランの特定
- ユーザーがパスを指定している場合 → そのプランを作業対象とする
- 指定がない場合 →
docs/PLAN/*/tasks.jsonを Glob で一覧し、AskUserQuestion で対象を選択
Step 2: validate スクリプトの実行
node .claude/skills/dev/fix-plan/scripts/validate-tasks-json.mjs docs/PLAN/{対象}/tasks.json
20 項目のチェック結果を確認:
- 全て PASS → Step 3 へ
- FAIL あり → Step 4 へ
Step 3: simulate スクリプトの実行
ダッシュボードと同じパース処理をローカルで再現:
npx tsx .claude/skills/dev/fix-plan/scripts/simulate-dashboard-parse.mjs docs/PLAN/{対象}
- エラーなく表示される → パース自体は正常。ダッシュボード側の問題の可能性
- エラーが発生 → エラーメッセージから原因を特定
Step 4: fix スクリプトで修復
validate / simulate で検出した問題のうち、自動修復可能なもの:
# 確認のみ
node .claude/skills/dev/fix-plan/scripts/fix-tasks-json.mjs docs/PLAN/{対象}/tasks.json --dry-run
# 実行
node .claude/skills/dev/fix-plan/scripts/fix-tasks-json.mjs docs/PLAN/{対象}/tasks.json
修復対象:
progress.total/progress.completedの再計算statusの再導出metadata.totalGates/metadata.totalTodosの再計算
Step 5: タイポの手動修正
validate でタイポが検出された場合（例: "done" → "completed"）は Edit で修正する。
スクリプトが出力する候補を参考にする:
#4 status value: got "done", expected one of: ... (did you mean "completed"?)
#10 steps structure: T1 step "...": kind="implementaton" (did you mean "impl"?)
Step 6: spec.md の再同期
node .claude/skills/dev/fix-plan/scripts/check-spec-sync.mjs docs/PLAN/{対象}/tasks.json
差分があれば:
node .claude/skills/dev/spec-run/scripts/sync-spec-md.mjs docs/PLAN/{対象}/tasks.json
Step 7: 修復結果の確認
- validate スクリプトを再実行して全項目 PASS を確認
- simulate スクリプトを再実行してパース結果が正しいことを確認
- 最終サマリーを報告
Step 8: スクリプトで解決しない場合
agents/dashboard-visibility-debug.md を読み、記載された調査手順に従う。
主な調査観点:
- GitHub 上のファイル確認（未 push など）
- GitHub API レスポンスのパース確認
- ダッシュボード側のフィルタリング（日付 / リポジトリ / サイズ）
- フロントエンド レンダリング
参照ソース
スクリプトが判定の正とするファイル。必要に応じて Read する:
dashboard/lib/plan-json-loader.ts— v2 パーサーdashboard/lib/types.ts— TasksJsonV2 型定義.claude/skills/dev/spec/references/templates/tasks.template.json— v2 テンプレートdashboard/lib/github.ts— GitHub API クライアント