# Clarify Expectation

> Use when a GitHub Issue (or a Slack report pasted into one) needs to become an approvable 期待 document before anyone designs or implements — the Issue is vague, mixes symptoms with guesses, or lacks Asis/Tobe, and the human gate ① review is next

- Skill: `yannsugi/clarify-expectation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yannsugi/clarify-expectation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yannsugi/clarify-expectation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: yannsugi (https://skillmd.com/u/yannsugi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yannsugi/clarify-expectation

---


# 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(解釈が引きずられる)
- 会話履歴。前回までの往復は期待文書と変更履歴に蒸留済みとみなす

## 手順

1. **トリアージ結果を読む** triage-issue の判定と根拠を期待節のトリアージ欄に転記する。未判定なら先に triage-issue を実行する。L で survey-codebase の結果が無ければ、それを先に実行する(未確認セルは⚠候補として受け取る)。S なら手順4〜6を1コメントに畳んでよいが、承認は省かない
2. **現状調査** 改修/新規、FE/BE/IaC/データの領域判定。事実は調査結果へ、仮説は仮説と明記
3. **質問ルーター** 湧いた疑問を3分類してから動く
   | 分類 | 判定基準 | 処理 |
   |---|---|---|
   | ビジネス判断 | 調べても決まらない。利用者・業務・優先度・スコープの選択 | 人間へ(Issue コメントで質問) |
   | 技術判断 | コード・ログ・設定を読めば決まる | 自分で調べて決め、根拠を「技術判断の根拠」へ |
   | 些末 | どちらでも品質に効かない | デフォルト案で進め「些末判断」に記録(通知のみ) |
   ビジネスか些末かで迷ったときだけ聞く側へ倒す。技術判断を人間に投げない
   回答を待たずに進める場合、暫定値は変更履歴に「暫定・回答待ち」と記す。些末判断には書かない(業務判断を些末に見せない)
4. **期待の詳細化** `assets/expectation.md` の書式で Issue 本文を書き直す。Asis/Tobe は「誰が・どこで・何をすると・何が起きる」の一行一観測
5. **E2E 語彙プリフライト** 期待節の各行を検査:
   - E2E(画面操作・API 呼び出し・ファイル着信・ログ出力)で観測できない行 → 書き直すか、コンテキストへ移す
   - クラス名・ライブラリ名・テーブル名・環境変数名などの実装語彙 → コンテキストへ移す
   - ⚠ は3つまで。超えたら統合するか、確信の低い順に残す。あふれた解釈は変更履歴に「暫定」として残す
6. **変更履歴** 初版でも1行書く。2回目以降は「どの回答・調査結果を受けて、どの行が、なぜ」
7. **出力** 新しい本文と、ゲート①向けの「変わった行と理由」の差分サマリ(ビジネス判断の質問があれば番号つきで列挙)を成果物として利用者に提示する。`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 に足す → スコープ拡張はビジネス判断。質問にして待つ