paperclip-triage

Paperclip のトリアージ

Paperclip の課題が AFK エージェントループに進める状態かどうかを判断します。

参照資料

通常のトリアージでは、まず次の資料を読みます。

• references/CONTEXT.md
• references/docs/paperclip-operator/afk-readiness.md
• references/docs/paperclip-operator/integration-matrix.md

課題が該当する領域に関わる場合に限り、残りの資料を開きます。

• references/docs/paperclip-operator/control-plane.md：エンティティの意味、親子構造、ブロッカー、コメント、ドキュメント、承認、アクティビティについて。
• references/docs/paperclip-operator/cli-contract.md：CLI／REST の認証、フォールバックの例、変更の検証について。

これらのプロジェクトドキュメントがない場合は、まず paperclip-setup を実行して、同梱テンプレートから作成します。

手順

1. 対象の課題、または課題一覧を読みます。

2. 課題ごとに、次の項目を確認します。

   • ステータス
   • プロジェクト
   • 親課題
   • 説明
   • 受け入れ条件
   • ブロッカーと blockedByIssueIds
   • 計画ドキュメント
   • コメント
   • 担当者（設定されている場合）
   • レビューが必要な場合の executionPolicy.stages[].participants におけるレビュアーのゲート
   • 人間による最終承認が必要かどうか。必要な場合、ユーザー承認ステージではなく、レビュアーのエージェントが冪等な request_confirmation の引き継ぎを担当する必要があります
   • 担当者の変更を推奨する前に、実行中、キュー登録済み、再試行中の実行を確認します
   • 想定される実行担当者のデフォルト環境とプロジェクトのワークスペース。オペレーターから要求されない限り、オーバーライドを提案しません

3. 対象範囲内の各課題を、次のいずれか1つに分類します。

   • AFK 対応可能
   • 情報が必要
   • ブロック中
   • 人間の対応が必要
   • 範囲が広すぎる
   • 修正が必要
   • キャンセル
   • 完了

   対象範囲内のすべての課題に、分類がちょうど1つ付いていれば完了です。

4. 具体的な変更を推奨します。AFK 対応可能でない各課題について、対応可能にするために不足している具体的な要素または変更が示されていれば完了です。

5. 承認を待ちます。

6. 承認された変更を適用します。

Wiki のソース資料

対応可能かどうかの判断が Paperclip の wiki URL、wiki ページのパス、または取得済みの wiki ソースに依存する場合は、paperclip-wiki-fetch を使って、課題を AFK 対応可能と分類する前にソースへアクセスでき、内容が十分であることを確認します。取得可能な場合は、取得したタイトル、パス、更新時刻、ハッシュを推奨内容に含めます。

認証情報、会社のスコープ、wiki ID、スペースのスラッグ、またはページのパスが不足していて wiki を取得できない場合は、課題を needs-info に分類し、「Readiness に不足している要素」に不足している wiki アクセス情報を記載します。

トリアージで古い、不足している、または誤った wiki の内容が見つかった場合は、フォローアップのスキルとして paperclip-wiki-manage を推奨します。オペレーターが明示的に wiki 管理へ切り替え、具体的な変更を承認しない限り、通常のトリアージで wiki の内容を変更してはいけません。

調査範囲の深さ

親課題をトリアージする際は、直接の子課題を確認します。オペレーターが「子タスク」と指定した場合、新たに計画された子課題がある場合、または対応可否の判断に孫課題が必要な場合は、子課題をもう1階層確認します。デフォルトでは大規模なツリーを再帰的にたどらず、深い階層のブランチは要約し、計画中の親課題が残っている子課題については paperclip-plan-work を推奨します。

推奨フォーマット

## Triage Recommendation

### <issue identifier/title>

- Classification:
- Current status:
- Recommended status:
- Missing readiness elements:
- Proposed comment:
- Proposed blocker links:
- Proposed reviewer gate:
- Proposed human confirmation:
- Follow-up skill:

大規模な課題ツリーでは、コンパクトモードを使用します。

## Triage Recommendation

- Parent summary:
- Executable now:
- Blocked:
- Needs planning/info:
- Approved mutations table:

ステータスのルール

• todo は、対応可能で着手できる状態を意味します。
• backlog は、保留中または着手できない状態を意味します。
• 具体的な課題間の依存関係には、第一級の blockedByIssueIds が必要です。コメントで担当者やブロック解除のアクションを説明できますが、オペレーターが明示的に劣化モードを承認しない限り、ブロッカーのリンクの代わりにはなりません。
• 範囲が広すぎる課題には paperclip-plan-work を使用します。
• トリアージの判断理由を説明するには、コメントを使用します。

変更のルール

まず推奨内容を報告します。ステータス、コメント、ブロッカー、ラベル、担当者、レビュアーのゲートを更新するのは、オペレーターの承認後に限ります。

承認済みの変更を適用する

ネイティブの変更を実行できる、最も限定的な Paperclip の手段を使用します。

• 必要なフィールドと検証に対応している場合は、まず CLI で課題の読み取り、更新、コメントを行います。
• CLI で操作を実行または検証できない場合は、MCP の課題ツールを使用します。
• CLI と専用の MCP ツールで公開されていない Paperclip ネイティブのフィールド、特に blockedByIssueIds と executionPolicy には、MCP の paperclipApiRequest を使用します。
• CLI と MCP が利用できない、または正常に動作しない場合に限り、REST を直接使用します。

CLI と専用の MCP ツールでブロッカーのリンクを書き込めない場合は、cli-contract.md の API フォールバックを使用します。

すべての変更について、課題を再度読み込んで検証します。ブロッカーを変更した場合は、返された課題に意図した blockedByIssueIds が含まれていることを確認します。オペレーターが明示的に縮退モードを承認していない限り、コメントのみの説明を同等のものとして扱わないでください。レビュアーのゲートについては、返された課題に意図した executionPolicy.stages[].participants が含まれていることを確認します。対象環境でマッピングが検証済みでない限り、reviewRequest を同等のものとして扱わないでください。

現在の課題詳細画面でコメント履歴を確認できない場合は、利用可能であればアクティビティ／コメント画面を確認します。それでもコメントを読めない場合は、推奨事項でその制約を明記し、トリアージ全体を中断するのではなく、表示されている課題フィールドに基づいて進めます。

承認済みのトリアージに委任が含まれる場合は、課題が未割り当ての間に、課題の概要、ブロッカーのリンク、コメント、ステータス、レビュアーのゲートを設定します。実行中または再試行中の実行がないことを確認してから、最後の変更として実行者を一度だけ割り当てます。割り当てによる起動がキューに登録されたら、変更を停止し、監視を paperclip-monitor に引き継ぎます。オペレーターから実質的に新しい必須情報が提供されない限り、実行者の通常の環境を上書きしたり、heartbeat/resume を呼び出したり、実行者に言及したり、追加のフォローアップコメントを加えたりしないでください。