mvp-docs

PLAN.md と JUDGE.md は対で作る。片方だけ作らない。

• PLAN.md — 何ができたら終わりか。着手前に書き、完成条件を先に固定する。
• JUDGE.md — なぜその実装なのか。実装中、判断を下したその場で1件ずつ追記する。

どちらも足場であり永続しない。README へ昇華した時点で削除する（repo-readme スキル §6）。

0. 前提：JUDGE.md の中身を私が創作しない

JUDGE.md は user の判断の記録であって、AI への指示ファイルではない。私が「なぜ X を選んだか」を埋めた時点で文書の意味が消え、その捏造が README の Design Decisions と docs/design-decisions.md にそのまま流れ込む。

私の役割は聞き取って記録すること。判断の理由が対話に出ていなければ、埋めずに user に聞く。選択肢の洗い出しと trade-off の提示は私がしてよい。選ぶのは user。

PLAN.md は叩き台を私が書いてよい。ただし完成条件とスコープは対話で確定させる。

0.5. フェーズとの接続（着手前に判定する）

この Skill は文書を書くだけで、実装の可否を決めない。 誰が実装するかは、リポの CLAUDE.md が宣言するフェーズと local-issue スキルの担当分離に従う。判定はそちらを読む。ここに転記しない。

書いた PLAN からそのままコードに入らないこと。ルートA（改修提案）は MVP 期の駆動文書ではないので、フェーズを問わず書いてよい。

ファイル衛生は repo-standardize スキル §3 に従う。枠だけ作って放置しない。

1. ルートの判定

置き場所はどちらも PLAN.md / JUDGE.md をリポ直下に置く。使い捨ての足場であり、目に入る場所に無いと更新されないまま腐る。docs/ へ入れない（あそこは README を1本の主張に保つための退避先で、公開後も残るもの。repo-readme スキル §7）。

判断はリポ単位で1本にまとめる。改修計画が複数並走する場合だけ PLAN-{topic}.md で分ける。

2. 作るタイミング

PLAN.md

• ルートA: 対象の現状を実測・実読してから書く。数値は推定でなく実測を入れ、見込みには「見込み」と明記する。
• ルートB: 対話で方向が見えた直後、コードを書く前。1行もコードを書いていない段階で完成条件を固定する。

JUDGE.md

• 最初の1件が出た時点で作る。空の枠を先に commit しない（repo-standardize スキル §3）。PLAN を書く過程で捨てた選択肢があれば、それが1件目になることが多い。
• 以後、判断を下したその場で追記する。実装が一段落してからまとめて書き起こさない（後からだと粒度が落ち、件数が膨らむ）。

3. ルートB の対話の順序

種別（Type A / B / C）が関わるのはこのルートだけ。ルートA は既存リポの土台を直す計画なので種別を問わない。

この順で確定させる。飛ばした項目は「未確定」節に残し、埋めたことにしない。

0. リポの種別（Type A / B / C）を決める — 判定木とリトマス試験は repo-readme スキル §1。ここに転記しない。DoD の形が種別で変わる（「作れた」か「使える」か「分かった」か）ため、完成条件より先に決める。決めた種別と、そう判断した理由は PLAN の冒頭に1行残す。
1. 誰が何に使うか（1〜2文）
2. 完成条件（DoD） — その種別の下限（repo-readme スキル §2）を README が満たせる状態から逆算する。加えて「実利用者が1日使える」×「第三者が価値を30秒で理解できる」（.claude/skills/module-dev/SKILL.md）。Type C は「結果の表が README 本文に出ている」が DoD に必ず入る（測るまで結論が未知なので、数字が出ない限り終われない）
3. やらないこと — ここで切らないと後から膨らむ
4. 概念の名前と境界 — エンティティ・処理段・情報ソースの区分。公開後 context/domain.md へ移す部分なので、PLAN 内でも独立した節に隔離して書く
5. 段取り — 依存関係つき

4. 粒度（この文書の本体）

JUDGE.md — 記録する判断の条件

次をすべて満たすものだけ書く。

1. 実在する選択肢が2つ以上あり、片方を捨てた
2. 後から変えるとコストがかかる（データ形式・公開面・依存の追加・境界の位置・外部との契約）
3. コードを読んでも理由が分からない

書かないもの:

• 規約・既存構成で自動的に決まったこと（conventions.md に書いてある、環境が Nix 管理、等）
• 実質1つしか選べなかったこと
• 実装中に自然に決まった細部（変数名・関数分割・ライブラリの API の使い方）
• 後から無コストで変えられること
• バグ修正の経緯・試行錯誤の記録（git log の領分）

件数の上限

目安は1リポ 7±2 件。10 件を超えたら粒度が落ちているサインとして、追記する前に既存項目を読み返し、統合できないか見る。統合できないなら、その追記自体が条件3件を満たしていない可能性を疑う。

上限は「重要な判断を落とすため」ではなく、細かい判断で大きな判断を埋もれさせないためにある。20 件並んだ JUDGE.md は、README にも docs/design-decisions.md にも昇華できない。

1件の分量

3〜6行。テンプレの4項目（判断 / 選択肢 / 決め手 / 再検討の境界）で収まらないなら、それは複数の判断が混ざっている。

「再検討の境界」（どの条件が変わったらこの判断を見直すか）を書けない項目は、そもそも判断ではなく作業メモである。この1行が粒度のフィルタとして一番効く。

PLAN.md — 作業単位の粒度

アクションプランの1行は「完了の目安が1行で書けるか」で切る。書けないなら粗すぎるので割る。逆に、完了の目安がコードの1箇所を指すだけなら細かすぎるので束ねる。

5. テンプレ

• templates/PLAN-cleanup.md — ルートA。各項を「現状 / 改善策 / 効果」で揃え、末尾に依存関係つきアクションプラン
• templates/PLAN-new.md — ルートB
• templates/JUDGE.md — 共通

節はテンプレの見出しから該当するものだけ使う。埋まらない節は消す。プレースホルダのまま commit しない（repo-standardize スキル §3）。

6. 出口

実装へ渡すとき: Issue ドリブン期なら、PLAN のアクションプラン1行を1 Issue として local-issue へ渡す。それ以外は相談者がそのまま実装し、判断を下すたび JUDGE.md に戻る。

README を書く段になったら repo-readme スキルへ渡す。PLAN の3仕分け（進捗は捨てる / スコープは README / 概念定義は context/domain.md）と削除はそちらの担当で、このスキルではやらない。