trellis-brainstorm

Trellis ブレインストーミング

譲れない計画のルール

構築、実装、修正、リファクタリング、または「進めてください」という依頼は、計画段階を終えてよいという承認ではありません。タスク作成への同意も、実装の承認ではありません。

重要度の高いタスクでは、実装を始める前に、最初の依頼の後でユーザーが少なくとも一度は応答する必要があります。確認事項がない場合、その応答では、以下に示す最終計画の概要を承認する必要があります。

ユーザーが決定すべきプロダクト、スコープ、UX、互換性、リスク、または受け入れ条件に未解決の項目がある間は、毎回、最も価値の高い質問を1つだけ最後に提示してください。プロダクトコードを編集したり、実装を割り当てたり、task.py start を実行したりしないでください。

譲れないエビデンスのルール

コードベースを調べれば答えられる質問は、代わりにコードベースを調査してください。

これは必須です。ユーザーに質問する前に、その答えがすでにコード、テスト、設定、ドキュメント、既存の仕様、またはタスク履歴にあるかを確認してください。

リポジトリから確認できる事実について、ユーザーに確認を求めてはいけません。ユーザーの意図、好み、スコープ、リスク許容度、受け入れ時の動作、または調査後も曖昧さが残る決定事項のみを尋ねてください。

リポジトリのエビデンスによって、現在の動作と技術的制約を確認できます。ユーザーが意図する動作、機能スコープの境界、UXの好みは、既存のパターンがある場合でも、リポジトリのエビデンスだけでは判断できません。既存のパターンは選択肢や推奨の根拠であり、決定そのものではありません。

---

このスキルは、Phase 1 の計画段階で使用し、ユーザーの依頼を明確な要件と計画成果物にまとめます。

前提条件

タスク作成への同意が得られ、ユーザーが Trellis の計画段階に進む準備ができている場合にのみ、このスキルを使用してください。

タスクがまだ存在しない場合は、作成してください。

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)

ユーザーの依頼から簡潔なタイトルを付けてください。タイトルと --description は、どちらも空欄にしてはいけません。create は空欄を拒否し、どちらかが空欄のレコードはアーカイブ時に拒否されます。日付プレフィックスを付けずにスラッグを作成してください。task.py create が MM-DD- のディレクトリプレフィックスを自動で追加します。

task.py create はデフォルトの prd.md を作成します。追加質問をする前に、現時点での理解を反映してそのファイルを更新してください。

計画の流れ

1. ユーザーの依頼と、最初に判明している事実を prd.md に記録します。
2. 質問する前に、利用可能なエビデンスを調査します。
   • コード、テスト、フィクスチャ、設定
   • README ファイル、ドキュメント、既存の仕様、ドメインに関するメモ
   • 関連する Trellis タスク、調査ファイル、存在する場合はセッション履歴
3. 判明した内容を次の項目に分けます。
   • 確認済みの事実
   • ユーザーから確認が必要なプロダクトの意図
   • ユーザーの判断が必要なスコープまたはリスク
   • スコープ外となる可能性が高い項目
4. ユーザーが決めるべき事項が残っている場合は、推奨案とトレードオフを添えて、最も価値の高い質問を1つだけ尋ねてください。その後は停止してください。同じターンで実装作業を行ってはいけません。
5. ユーザーの回答のたびに prd.md を更新し、判断事項の一覧を再評価して、手順2から繰り返してください。
6. ユーザーが決めるべき事項がなくなったら、複雑なタスクでは design.md と implement.md を作成または更新してください。
7. 要件の収束ゲートを実行してから、PRD の収束レビューを行ってください。
8. 最終計画の概要を提示し、停止してください。同じターンで task.py start を実行したり、プロダクトコードを編集したりしてはいけません。
9. その後のユーザーのメッセージで、最新の計画概要が明示的に承認された場合にのみ、task.py start の実行と実装が許可されます。承認後に成果物に重大な変更があった場合は、最終レビューをやり直してください。

プロジェクト固有のプロダクト／仕様の階層を作り上げてはいけません。リポジトリにプロダクト、ドメイン、仕様のドキュメントがすでにある場合は、それらを使用してください。ない場合は、利用可能なエビデンスに基づいて進めてください。

質問ルール

1つのメッセージにつき、質問は1つだけにしてください。

各質問には、次の内容を含めてください。

• 必要な決定事項
• 回答が重要な理由
• 推奨する回答
• 推奨とは異なる選択をした場合のトレードオフ

検索、ファイルの調査、ブレインストーミングの続行など、プロセスに関する質問はしないでください。証拠の調査は自分で直接行ってください。ユーザーに尋ねるのは、残っている課題がプロダクト上の決定、好み、スコープの境界、またはリスク許容度の選択である場合に限ります。

推奨事項はデフォルトの選択肢ではありません。ユーザーが実装を依頼したというだけで、推奨するプロダクト上の決定をユーザーに代わって選ばないでください。

依頼内容とリポジトリの証拠からすべての決定事項がすでに明らかな場合、無理に確認の質問を作らないでください。その場合は、後続の明示的な承認が必要な最終計画サマリーを直接提示してください。

最終レビューは必須のフェーズ移行ゲートであり、禁止されているプロセスに関する質問ではありません。タスク作成への同意、最初の実装依頼、最新の最終サマリーを提示する前に得た承認は、このゲートを満たしません。

思考フレームワーク：第一原理分析

要件が曖昧な場合、解決策が過剰に複雑に感じられる場合、または「みんなそうしているから」という理由で複雑さを加えようとしている場合は、まず基本的な事実に分解してから考えを組み立ててください。

ステップ1：問題を言い換える

実装の詳細を取り除き、1文にまとめてください。

悪い例：「ユーザープロフィールのエンドポイントにRedisキャッシュを追加する必要があります」 良い例：「ユーザープロフィールの読み込みに時間がかかりすぎています」

ステップ2：基本的な事実を列挙する

絶対に正しいことは何ですか（意見や慣習ではありません）。

カテゴリ	例
物理的な制約	ネットワーク遅延は0以上、ディスクI/Oには上限がある
ビジネスルール	「ユーザーには自分のデータを表示する必要があります」
技術的な不変条件	「データの一貫性を保つ必要があります」
ユーザーのニーズ	「ユーザーはXをY秒以内に求めています」

ステップ3：前提を見直す

現在の計画の各要素について、次を確認してください。

• 事実ですか、それとも慣習ですか？ 「常にRESTを使っています」—なぜですか？
• これを取り除いたらどうなりますか？ 何も壊れないなら、不要です。
• 実際の問題を解決していますか、それとも症状を解決していますか？ 因果関係をたどってください。
• この複雑さによって誰が恩恵を受けますか？ 「誰もいない」なら、簡素化してください。

ステップ4：事実から組み立てる

1. すべての事実を満たす最小限の実用的な仕組みから始めます
2. 特定の事実が必要とする場合にのみ、複雑さを加えます
3. 追加する要素ごとに、「どの事実がこれを必要としていますか？」に答えられるようにします

ステップ5：検証する

• 解決策は元の問題を解決していますか？
• 検証が必要な前提は何ですか？
• これを検証する最も簡単な実験は何ですか？

要件収束ゲート

最終レビューの前に、次のすべてを確認してください。

• ユーザーが得る成果とプロダクトの価値が明確である
• 対象範囲内と対象範囲外の動作が明確である
• 受け入れ基準が、観察可能な結果を示している
• ユーザーが決定するプロダクト、スコープ、UX、互換性、リスクに関する事項が解決済みである
• 作業を妨げる未解決の質問がない
• 技術的な不明点が調査済みであるか、MVPの動作を変えずに明示的に先送りされている

軽量なタスクではdesign.mdとimplement.mdを省略できます。ただし、証拠の調査、要件の収束、最終レビュー、新たな実装承認を省略することはできません。

最終計画サマリーには、Goal、In Scope、Out of Scope、Acceptance Criteria、Key Decisions、関連するRisksまたはDeferred Items、および成果物の状況を示す必要があります。

成果物のルール

prd.md には要件と受け入れ基準を記録します。

• 目標とユーザー価値
• 確認済みの事実
• 要件
• 受け入れ基準
• スコープ外
• 計画を妨げている未解決の疑問

design.md には複雑なタスクの技術設計を記録します。

• アーキテクチャと境界
• データフローとコントラクト
• 互換性と移行に関する注意事項
• 重要なトレードオフ
• 運用上またはロールバックに関する考慮事項

implement.md には複雑なタスクの実行計画を記録します。

• 順序立てた実装チェックリスト
• 検証コマンド
• リスクのあるファイルまたはロールバックポイント
• task.py start 前のフォローアップチェック

軽量なタスクは prd.md のみで構いません。複雑なタスクは task.py start の前に prd.md、design.md、implement.md を揃える必要があります。

implement.md は implement.jsonl の代替ではありません。サブエージェントディスパッチのワークフローでは、task.py start の前に implement.jsonl と check.jsonl のそれぞれに、実際の仕様または調査のエントリが少なくとも 1 件含まれている必要があります。空のマニフェストや、レガシーな _example プレースホルダー行のみを含むマニフェストはカウントされません。インラインワークフローでは、フェーズ 2 が trellis-before-dev を通じてコンテキストを読み込むため、この JSONL ゲートはスキップされます。

PRD 収束パス

計画準備完了を宣言する前、または task.py start を実行する前に、上記の成果物ルールで説明されている最終構造に照らして prd.md を一度書き直してください。これは任意のクリーンアップではなく、最終的な計画ゲートです。

このパスはロスレスでなければなりません。

• 繰り返し現れる事実は 1 つの権威あるセクションに統合する。
• What I already know、Assumptions、解決済みの Open Questions などの一時的なブレインストームセクションは、目標、背景、要件、技術メモ、または受け入れ基準に折り込む。
• 解決済みの未解決の疑問は、空のセクションや回答済みのセクションを残すのではなく削除する。
• 並行するバグリストと要件リストが同じ作業を記述している場合は統合し、各不具合の重要度、エビデンス、file:line アンカーはそれを所有する要件に保持する。
• すべての file:line アンカー、決定、制約、要件 ID、受け入れ基準のマッピングを保持する。
• ブロッキングな未解決の疑問が 1 つでも残っている間は、最終レビューに進まないでください。

パスの後、prd.md を上から下まで読み、新しい情報を追加しない限り、セクション間で事実が重複していないことを確認してください。

品質基準

計画準備完了を宣言する前に:

• prd.md にテスト可能な受け入れ基準が含まれている。
• prd.md が PRD 収束パスを通過している。未解決の一時的なブレインストームセクションがなく、セクション間で事実が重複しておらず、アンカー、決定、受け入れ基準のマッピングが失われていない。
• リポジトリから回答できる疑問は、調査によってすでに回答済みである。
• ブロッキングな未解決の疑問が空である。
• 複雑なタスクには design.md と implement.md がある。
• サブエージェントディスパッチのタスクには、implement.jsonl と check.jsonl の両方に厳選された実際のエントリがある。シードのみのマニフェストは準備完了ではありません。
• 最新の最終計画サマリーがユーザーに提示されている。
• 後続のメッセージで、ユーザーがそのサマリーを実装のために明示的に承認している。

ユーザーが当初実装を求めたというだけの理由で実装を開始しないでください。