writing-issues

Issue の書き方

必須の前提: technical-writing スキル(厳格なルール、真実に関するルール、スタイル)。

概要

中心となる原則: 自分がいなくても通用するように Issue を書く。 成果を明記し、Done を決める受け入れ確認を含め、あらゆる判断の根拠をリンクし、未解決部分ごとに担当者を明記します。

呼び出すべき場合、そうでない場合

トラッカーの項目を書いたり編集したりするとき、バグを起票するとき、作業をチケットに分割するとき、受け入れ基準を書くときに呼び出します。代替案を比較検討するために呼び出してはいけません。Issue で設計を論じる必要がある場合は writing-design-docs の役割です。Issue は設計ドキュメントをリンクするもので、その内容をインライン展開することは決してありません。このスキルが扱うのは執筆のみで、優先順位付けやワークフローに関する助言は扱いません。

まず読むことはトラッカーにも当てはまります。同じ種類の最近の Issue を最大 2 件読み、起票前にその慣習に合わせます。トラッカーにそれより少ない件数しかない場合は、存在するものを読んで、そのまま起票します。

報告者が対応できない場合は、ブロックするのではなく、明示した不足項目とともに起票します。technical-writing のチェックポイント(種類、想定読者、目的、非目標)は、立ち止まって確認すべき事項です。不足している内容の詳細(再現手順、ログ行、過去のインシデントへのリンク)は、Issue 内で明示的に担当者を割り当てた未解決項目になります。

自分がいなくても通用するかのテスト

すべての Issue は、赤の他人が尋ねるであろう 4 つの問いに答えます。

1. どのような成果か? これが完了したときの世界の状態であり、そこに至る手順ではありません。実装は計画に属します。
2. Done を決めるのは何か? 具体的で、独立して検証可能な受け入れ確認。「エラーを適切に処理する」は何も決めません。「アップロードの失敗時に再試行バナーを表示し、WARN レベルでログを記録する」は決めます。
3. 根拠は何か? 判断や制約が根拠に基づく場合は、その出典をリンクします。リポジトリのパス、ドキュメント、URL などです。
4. 未解決部分の担当者は誰か? 名前や役割のない「引き続き調査が必要」は禁止された曖昧な担当者です。1 名を指名するか、そのフィールドを明示的に未割り当てとしてマークします。

Issue の種類

トラッカーごとに 1 つの用語集を、それぞれ 1 行で定義し、一貫して使用します。

種類	定義
Epic	一連の作業。その説明には成果を明記し、設計ドキュメントをリンクする
Story	ユーザーに可視の価値があるもの。ユーザーの立場から書く
Task	ユーザーに可視の面がないエンジニアリング作業
Bug	欠陥。現在の挙動が意図した挙動と矛盾している
Spike	タイムボックス付きの調査。その成果物はコードではなく判断である

Spike の Done は、記録された判断( recording-decisions を参照)であり、決して「調べた」ではありません。

判断とそれに続く一連の作業は 2 つの形に当てはまります。まず Spike を行い、判断後に Epic を起票する形か、最初の受け入れ項目が承認された設計ドキュメントである Epic の形です。どちらも有効です。1 つを選び、どちらかを明言します。

Story と Task の骨子

Issue の説明は、何をなぜ行うかの仕様です。

**Problem / Why:** [the observable problem, from the reader's seat, with numbers where they exist]

**Outcome:** [the state of the world when done; not the steps]

**Acceptance:**
- [ ] [independently testable check]
- [ ] [another]

**Out of scope:** [what this issue deliberately does not cover]

**Open items:** [each with a named owner or role, or an explicit "unassigned"]

**Sources:** [repo paths, documents, measurements behind the above]

writing-design-docs の 5 つの曖昧さの欠陥を、受け入れ項目のリストに適用します。「何をどのように」を欠く、または「検証可能な出力がない」受け入れ確認は、検証可能ではありません。

Gherkin 形式の given/when/then は、チームが使用している場合、受け入れ確認の形式として認められます。どちらの場合も同じ検証可能性の基準が適用されます。INVEST(independent、negotiable、valuable、estimable、small、testable)は、Story のサイズチェックとして機能します。「small」または「testable」を満たさない Story は、起票前に分割します。

バグ報告の骨子

症状を最初に。次の読み手はそのエラーを探してたどり着くからです。

**Symptom:** [verbatim error string or observable misbehavior, searchable]

**Reproduction:** [numbered steps, one action each, from a clean state]

**Expected:** [what should happen, with the source that says so, or an explicit "no written source found" rather than a fabricated reference]
**Actual:** [what happens]

**Environment:** [version, platform, config that matters]

**Open items:** [each with a named owner or role, or an explicit "unassigned"]

**Suspected cause:** [only if investigated; labeled as hypothesis, never stated as fact]

タイトルには診断ではなく症状を書きます。原因が検証されていない限り、「スケジューラの競合状態」ではなく「リマインダー時刻にリマインダーが重複する」とします。

ルール

• 1つのホーム。 課題は「何を」「なぜ」を管理し、リポジトリ内の計画は「どのように」を管理します。2つの生きたコピーを決して維持しないでください。
• チケットキー。 チケットキーはコミットと計画ドキュメントに存在し、コード、コメント、テスト名、ユーザー向け文字列には決して存在しません。
• 課題のステータスではなく、コードを信頼する。 自己申告の状態はすぐに古くなります。インポートされた課題や古い課題に基づいて構築する前に、リポジトリに対して検証してください（シンボルを grep し、履歴を確認する）。
• 追記し、書き換えない。 進行中の課題に対するスコープの変更は、日付入りの追記ノートであり、無言の編集ではありません。完了後に見つかったフォローアップ作業は新しい課題であり、クローズされた課題への編集では決してありません。
• サブタスク。 レビュー可能な粗いスライスであり、すべての細かいステップではありません。細かいステップは計画に存在します。
• 見積もり。 見積もりとしてラベル付けし、何に依存するかを明記します。
• 課題のクローズ。 理由を記録します。特に won't-fix と重複の場合は重要です。