show-me-your-work

作業記録を残す

正規ログは1つにします。

形式

単一のTSVファイルを使い、判断ごとに1行記録します。各セルは1行に収めます。エビデンスは説明文ではなく、参照先です。

references/decision-log-template.tsv（ヘッダー行）をコピーして、新しいログを作成します。列は次のとおりです。

• ts. ISO8601形式のタイムスタンプ。
• phase. フェーズまたは作業の流れ。
• decision. 選択したこと、または実施したことを1行で記します。
• why. 理由を平易な言葉で記します。原則が判断の根拠になった場合は、専門用語のタグにせず、はっきり書きます。
• evidence. それを証明するリンクまたはパス：コミットSHA、PR番号、file:line、成果物、トレース、スクリーンショットのパスなど。段落は記載しません。
• result. 結果または判定状態：tests green、reverted、pixel-diff 0、INCONCLUSIVE、open。

レビュー担当者がひと目で読めるよう、平易な言葉で書いた例です。

ts	phase	decision	why	evidence	result
2026-05-24T09:02:00Z	frame	counted the work first, about 100 components and roughly 75 hours	wanted to know the size before starting a long run	commit 3a9f1c2	found 5 things to sort out before starting
2026-05-24T09:40:00Z	harness	took screenshots of the old version before changing anything	so we can compare old against new and catch any visual change	scripts/snapshot.sh, baseline/	saved 120 reference screenshots
2026-05-24T11:15:00Z	widget	moved the widget styles over without changing how it looks	keep the change small and the result identical	commit 7c21e0a, pixel-diff 0	looks identical, tests pass
2026-05-24T12:30:00Z	widget	threw out a helper's work because its screenshots were blank	checked the real files instead of trusting its summary	worktree reset	reverted, tightened the instructions for next time

行を記録する

各項目は、実施したことをチームメイトに伝えるように書きます。平易な言葉で具体的な行動を記し、AIらしい表現や抽象的な専門用語は使いません。ログのテキストにも unslop スキルを使います。

ヘルパー scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result> を使います。このヘルパーは ts を記録し、初回使用時にヘッダーを書き込み、余分なタブや改行を取り除き、=、+、-、@ で始まるセルの先頭にシングルクォートを付けます。委任した作業の行も含め、すべての行でこのヘルパーを使います。

チェックアウトのクリーンアップ後も保持する必要があるエビデンスには、エビデンス取得ヘルパー を使います。完了したマニフェストのパスを既存の evidence セルに記載します。元のチェックアウトを削除する前に、その成果物を検証します。ハンドオフでは、選択した絶対パスを引き継ぎます。

失敗したレビューラウンドも含め、すべての判定、完了条件の変更、すべての制約を記録します。各制約の decision セルには、根拠となる参照先とともに user-given、self-imposed、unknown のいずれかを記します。後から追加する行には実際の追記時刻を記録し、分かる場合は先に起きた出来事の時刻も記します。ほかの判断ポイントやチェックポイントも記録しますが、すべての行動を記録する必要はありません。選んだ分岐、検証結果とともに完了した単位、きっかけとなった事象を含む方針転換や取り消し、表面化したブロッカー、修正したゲートなどを記録します。ループ実行では、1回の反復につき1行記録します。些細なことや自明なことは省きます。

1回の実行とは、後続のターンやその要約も含めた、1つのエージェントとの会話です。作業の引き継ぎ、エージェントの交代、新しいチャットは、新しい実行の開始となります。既に行があるログに実行が追記する場合、その最初の行のフェーズは start とします。また、別の実行の start 行の後に続く最初の行も同様です。そのため、後のターンでログに戻ってきた実行は、まずログの末尾の行を読み、別の実行がその後に記録していないか確認します。start 行には、この実行が記録していない直前の行の ts 範囲を記し、エビデンスにはエージェントIDなど、この実行を特定する情報を記します。start はほかの用途には使いません。

保存場所

デフォルトでは、ログは作業中の成果物であり、コミットしません。作業ディレクトリの decisions.tsv、または複数の取り組みが同時に進行する場合は .audit/<task-slug>.tsv に保存し、Gitの管理対象から外します。

レビュー担当者が結果を信頼するために記録が必要となるほど大規模な作業の場合に限り、ログをコミットします。コミットを予定する記録には、最初の行から、マージ後の想定読者が利用できる永続的なエビデンスを使います。コミットした記録のすべてのエビデンスポインターは、マージとチェックアウトのクリーンアップ後にも有効でなければなりません。コミット、PR、チェックイン済みファイル、または公開先と保持条件が想定読者に適した成果物を使います。プライベートな絶対パスだけでは不十分です。一時的な履歴のみを含む記録はローカルに残し、追記専用の行を維持します。読者が永続的なレビューを必要とする場合は、永続的なエビデンスを含む別の要約を公開します。ローカルの記録ではローカルの成果物を参照できますが、後のレビューに必要なエビデンスは取得ヘルパーを使って保持します。

ルール

• 追記専用です。判断が誤っていた場合は、それを置き換える新しい行を追加します。履歴を編集したり削除したりしてはいけません。
• 手作業で作る一回限りのものより、コミット済みスクリプトが生成するエビデンスを優先します（encode-lessons-in-structure 原則スキル）。

トランスクリプトと照合してログを監査する

実行の最後に、引き渡す前に、ログが事実を記録しているか確認してください。このワークスペースのセッションストアから、今回の実行のトランスクリプトを読んでください。場所を特定するには pstack-harness スキルを使用してください。他のワークスペースのストアは読まないでください。無関係なプライベートチャットが含まれています。今回の実行のトランスクリプトを見つけられない、または読めない場合は、行を確認しないでください。Attention セクションに、監査を実施できず、ログをトランスクリプトと照合して確認していないと記載してください。それ以外の場合は、今回の実行の行を実際に起きたことと照合してください。行のまとまりはそれぞれ、今回の実行の start 行、または今回の実行でログが作成された場合は最初の行から始まり、別の実行の次の start 行で終わります。

• すべての行が、実際の判断または行動に対応しているか確認してください。
• 各行の根拠をたどれ、その行の主張を裏付けているか確認してください。
• 作業に影響を与えたにもかかわらず記録されていない分岐、方針転換、断念したアプローチがあれば、漏れとして追加してください。

ストーリーではなく、ログを修正してください。監査で行を編集したり削除したりすることはありません。実際の判断にも行動にも対応していない行や、主張または根拠が誤っている行がある場合は、実際に起きたことと、たどれる参照先を記した行を追加して、その行を置き換えてください。この監査では、今回の実行のまとまり以外の行は確認しません。今回の実行の作業から他の行の誤りが判明した場合は、誤った判断と同様に置き換えてください。

トレイルのクロスモデルレビュー

引き渡す前に、trail reviewer ロールのレビュアーサブエージェントを起動してください。ロールを解決するには pstack-harness スキルの Spawn a role セクションを使用してください。起動の呼び出しと、判定および返信における実行主体の開示について、そのセクションに従ってください。解決結果に記載されていないモデルを選んではいけません。自己レビューは代わりになりません。サブエージェントは監査トレイルと今回の実行のトランスクリプトを読み、ユーザーが注意すべき点を指摘します。作業をやり直すのではなく、最適でない点やリスクのある点を確認します。

• 根拠が弱い、またはない状態で記録された判断。
• 省略された検証手順や、トランスクリプトに証拠がないのに実施したとする検証。
• 後から見るとリスクがある選択（時期尚早、スコープの拡大、症状の取り繕い）。
• ざっと目を通しただけではユーザーが見落としそうな漏れ。

トレイルを作成した実行では、すべての返信の末尾に「Attention」セクションを付けてください。まず、レビュアーのモデル名と作業量を、それぞれ単独の行に記載してください（reviewed by <model>@<effort>。ロール名が trail reviewer でない場合は、そのロール名も記載します）。続けて、特定の行または箇所を参照しながら、未解決の重要な指摘を列挙してください。以前から報告されていて、現在も当てはまる指摘は、識別情報、現在の影響、根拠を含めて簡潔に記載してください。認識しただけでは指摘は解決しません。解決済みの指摘と、現在のリスクや対応に影響しない過去の繰り返しは省略してください。「指摘なし」も有効な値です。モデル名は省略できません。

トレイルの確認

上から順に読み、根拠の参照先をたどり、抜き取り確認してください。GitHub では、コミット済みの TSV は表として表示されます。column -s$'\t' -t decisions.tsv を実行すると、ターミナルに整形して表示されます。

このスキルの作成

他のスキルは監査トレイルを独自に作るのではなく、ここに誘導してください。名前で参照し、形式の定義はこのスキルに任せてください。列を繰り返し記載しないでください。