yannsugi clarify-expectation
解明フェーズ。Issue の曖昧さを解消し、人間がゲート①で承認できる「期待」に落とす。
思想は ${CLAUDE_PLUGIN_ROOT}/DESIGN.md の「解明フェーズの規律」「Issueの2部構成」節。迷ったらそこへ戻る。
核: 人間に届くのはビジネス判断だけ。期待は E2E で観測できる語彙だけで書く。
入力契約
読んでよいもの(全列挙):
- 対象 Issue の本文・コメント(
gh issue view <n> --comments)、および Issue 内リンク先。トリアージ結果と網羅的調査の結果はここに含まれる - コードベース(README・設計メモを含む。現状調査のため。読んだ事実は「コンテキスト > 調査結果」へ)
assets/expectation.md(このスキル同梱の出力書式)${CLAUDE_PLUGIN_ROOT}/DESIGN.md
読んではいけないもの:
- 他 Issue の実現案・実装 PR(解釈が引きずられる)
- 会話履歴。前回までの往復は期待文書と変更履歴に蒸留済みとみなす
手順
- トリアージ結果を読む triage-issue の判定と根拠を期待節のトリアージ欄に転記する。未判定なら先に triage-issue を実行する。L で survey-codebase の結果が無ければ、それを先に実行する(未確認セルは⚠候補として受け取る)。S なら手順4〜6を1コメントに畳んでよいが、承認は省かない
- 現状調査 改修/新規、FE/BE/IaC/データの領域判定。事実は調査結果へ、仮説は仮説と明記
- 質問ルーター 湧いた疑問を3分類してから動く
分類 判定基準 処理 ビジネス判断 調べても決まらない。利用者・業務・優先度・スコープの選択 人間へ(Issue コメントで質問) 技術判断 コード・ログ・設定を読めば決まる 自分で調べて決め、根拠を「技術判断の根拠」へ 些末 どちらでも品質に効かない デフォルト案で進め「些末判断」に記録(通知のみ) ビジネスか些末かで迷ったときだけ聞く側へ倒す。技術判断を人間に投げない 回答を待たずに進める場合、暫定値は変更履歴に「暫定・回答待ち」と記す。些末判断には書かない(業務判断を些末に見せない) - 期待の詳細化
assets/expectation.mdの書式で Issue 本文を書き直す。Asis/Tobe は「誰が・どこで・何をすると・何が起きる」の一行一観測 - E2E 語彙プリフライト 期待節の各行を検査:
- E2E(画面操作・API 呼び出し・ファイル着信・ログ出力)で観測できない行 → 書き直すか、コンテキストへ移す
- クラス名・ライブラリ名・テーブル名・環境変数名などの実装語彙 → コンテキストへ移す
- ⚠ は3つまで。超えたら統合するか、確信の低い順に残す。あふれた解釈は変更履歴に「暫定」として残す
- 変更履歴 初版でも1行書く。2回目以降は「どの回答・調査結果を受けて、どの行が、なぜ」
- 出力 新しい本文と、ゲート①向けの「変わった行と理由」の差分サマリ(ビジネス判断の質問があれば番号つきで列挙)を成果物として利用者に提示する。
gh issue edit <n> --body-fileでの本文置換とgh issue commentでの投稿は、利用者が明示的に指示した場合にのみ実行する
試走でローカルファイル <name>.md を対象にする場合は、本文を <name>.expectation.md、ゲート①コメントを <name>.comment.md に書く(edit と comment の2成果物に対応)。
よくある失敗
- 人間への質問が5つ以上ある → ルーターを通していない。技術判断と些末を引き戻す
- Tobe に「原因」「修正方法」が書いてある → 実現案の語彙。Tobe は振る舞いだけ
- 影響画面に内部サービス名やコンテナ名が並ぶ → 利用者から見える入口に言い換える。利用者が実際に叩く接続先(URL・ポート・エンドポイント名)は入口なので書いてよい
- 出典にローカルパスを書く → Issue/Slack の URL を書く。手元のパスは調査結果へ
- 報告に無い要求(監視・恒久対策)を Tobe に足す → スコープ拡張はビジネス判断。質問にして待つ