issue-writing

---

name: issue-writing description: Writing well-structured GitHub issues — standard templates, removal issue discipline, design doc references, test update requirements, epic sizing, and dependency declaration

Issue Writing

よく書かれたissueは、ファイルした人と実装する人の間の契約です。曖昧なissueは曖昧なPRを生み出します。具体的な受け入れ基準は検証可能な実装を生み出します。

標準 Issue テンプレート

すべてのissueは、タイプに関わらず、この構造を使用します:

## Problem

1文で: 何が間違っているか、または欠けているか、およびそれがなぜ重要か。

## Background

実装者が必要とするコンテキスト。関連するissue、PR、ADR、またはディスカッションにリンクします。
簡潔に — 3～4文以上必要な場合は、代わりにドキュメントにリンクしてください。

## Design Documentation

<!-- REQUIRED — choose one: -->
- Relevant: [ADR-0003](docs/decisions/0003-...), [Design Doc](docs/design/...)
- None available — implementation is the spec.
- Conflict: [ADR-0002](docs/decisions/0002-...) specifies X but this issue proposes Y.
  See Background for rationale.

## Acceptance Criteria

- [ ] 1. 完了時に真である必要があることの具体的で検証可能なステートメント
- [ ] 2. 各項目は独立してチェック可能 — 「また」を含む項目はない
- [ ] 3. ...

## Test Updates

<!-- REQUIRED — choose one: -->
- Tests added/updated: describe what scenarios are covered
- No test changes needed: [reason]
- Coverage: patch coverage must not regress below [N]%

## Out of Scope

このissueが対象としていない関連事項を明確にリストします。これはスコープ拡大と「ついでに」追加を防ぎます。

- Not in scope: [関連しているように見えるが、そうではない事項]

## Dependencies

- Blocked by: #N (これが開始される前にマージされる必要がある)
- Blocks: #N (これはそれが開始される前にマージされる必要がある)
- None

## Definition of Done

- [ ] All acceptance criteria checked off
- [ ] Tests pass, coverage not regressed
- [ ] architect-reviewer conformance table in PR body (all CONFORMANT)
- [ ] Design docs updated if needed (or separate issue filed: #N)
- [ ] Verification commands pass (removal issues only — see below)

---

削除 Issue — 特別ルール

削除は常にスタンドアロンのissueでなければなりません。 「X を削除」と「Y を追加」を同じissueにバンドルしないでください。バンドルすると削除が延期されることが保証されます — 新機能がリリースされ、古いコードが残ります。

削除が些細な小規模の場合（10行未満、5分未満）、追加に付随することができます。それ以外のすべて: 別のissueとしてください。

必須: Verification セクション

すべての削除issueには、削除が発生したことを機械的に確認するシェルコマンドを含む Verification セクションが必要です。これらのコマンドはissueが完了したときにゼロマッチを返す必要があります。これらは受け入れ基準です — issueを閉じる前に実行してください。

## Verification

実装後にこれらのコマンドを実行します。すべてが0マッチを返す必要があります:

```bash
# Old class is gone
grep -r "OldClassName" src/ tests/

# Old API endpoint removed
grep -r "/api/v1/legacy" src/

# Old dependency removed
grep "old-package" pyproject.toml

いずれかのコマンドがマッチを返す場合、issueは完了していません。

### 必須: 納品物としてのテスト更新

削除されたコードを実行していたテストは、**書き直す**必要があります — 削除しないでください、互換性shim経由で合格させたままにしないでください。

これをissueで明示的に述べます:

```markdown
## Test Updates

- `tests/test_pipeline.py::test_legacy_stage` — ステージがパイプラインの出力から欠けていることをアサートするように書き直します。パイプラインがクラッシュしないだけでなく。
- `tests/test_api.py::test_v1_endpoint` — 200ではなく404をアサートします。

目標: テストが削除が発生したことの肯定的な証拠になること、単に何も壊れなかったという証拠ではなく。

削除 Issue テンプレート

## Problem

[OldThing]は[理由]のため不要になりました。これはメンテナンス負荷 /
デッドコード / 混乱を追加し、価値を提供していません。

## Background

[OldThing]は[元の目的]のため#Nで導入されました。その目的は現在[NewThing / 変更された要件]によって果たされています。

## Design Documentation

- [ADR-0007](docs/decisions/0007-...): [OldThing]が廃止されることを指定します

## 削除対象

- `src/module/old_thing.py` — 完全に削除
- `src/pipeline.py:142-156` — コールサイトを削除
- `tests/test_old_thing.py` — 書き直す（テスト更新を参照）

## Acceptance Criteria

- [ ] 1. [OldThing]クラス/関数/モジュールはコードベースにもう存在しません
- [ ] 2. すべてのコールサイトが削除されたか[NewThing]に移行されました
- [ ] 3. テストが新しい予期された状態をアサートするように書き直されました（削除されただけではない）

## Test Updates

- `tests/test_old_thing.py::test_X` — [新しい予期された状態]をアサートするように書き直します

## Verification

```bash
grep -r "OldThing" src/ tests/       # must return 0 matches
grep -r "old_thing" src/ tests/      # must return 0 matches

Out of Scope

• [NewThing]の実装 — #Nで追跡
• 外部ユーザーの移行 — #Nで追跡

Dependencies

• Blocked by: #N ([OldThing]を削除する前に[NewThing]が存在する必要があります)

Definition of Done

• All acceptance criteria checked off
• Verification commands return 0 matches
• Tests rewritten (not deleted) to assert new expected state
• architect-reviewer conformance table in PR body

---

## デザインドキュメント参照

すべてのissueはデザインドキュメントに対処する必要があります。正確に3つの有効な状態があります:

### 1. デザインドキュメントが存在し、関連性があります
これらをリストしてください。ファイル全体ではなく特定のセクションにリンクしてください。

```markdown
## Design Documentation

- [ADR-0003](docs/decisions/0003-use-langgraph.md), §3 — このissueが実装するエージェント
  ループ構造を指定します
- [Design: Pipeline Stages](docs/design/pipeline.md), "Stage Interface" — このissueが
  適合する必要があるインターフェースを定義します

2. デザインドキュメントが存在しません

これを明示的に述べてください。これは覆い隠すべきギャップではありません — これは実装が仕様であり、将来の決定はPR/issueを参照すべきであることを意味します。

## Design Documentation

このエリアをカバーするデザインドキュメントはありません。このissueでの実装上の決定は、
デファクト仕様になります。

3. 既存のデザインドキュメントとの競合

競合を明示的にフラグしてください。デザインドキュメントから黙って逸脱しないでください。

## Design Documentation

⚠️ Conflict: [ADR-0002](docs/decisions/0002-...)はアプローチXを指定しますが、このissueは
[理由]のためアプローチYを提案します。このissueはADR-0002を廃止します。
更新された決定を文書化するための新しいADRが提出されるべきです（依存関係を参照）。

デザインドキュメントを更新する必要があるとき

このissueを実装すると既存のデザインドキュメントが古くなったり不正確になったりする場合は、 ドキュメント更新の別issueを提出してリンクしてください:

## Dependencies

- Blocks: #N (新しいパイプラインインターフェースを反映するようにADR-0003を更新)

ドキュメント更新issueは並列にまたは直後にマージできますが、忘れてはいけません。 コードと矛盾するドキュメントはドキュメントなしより悪いです。

---

テスト更新要件

すべてのissueでテスト期待を明示的に述べてください。実装者の判断に任せないでください。

状況	必須ステートメント
新機能	「[シナリオX、Y、Z]のテストを追加」
バグ修正	「このバグを検出したであろうリグレッションテストを追加」
削除	「[テスト名]を新しい予期された状態をアサートするように書き直す」
リファクタリング	「既存テストは合格し続ける必要があります；パッチカバレッジは回帰しない必要があります」
テスト変更なし	「テスト変更は不要です。[具体的な理由]」

カバレッジフロア

プロジェクトがカバレッジを追跡する場合、フロアを明示的に述べてください:

## Test Updates

パッチカバレッジは85%以上のままである必要があります。新しいコードは追加されたテストでカバーされる必要があります。

---

Epic とマイルストーンの規律

サイズ制限

Epic は10issueを超えてはいけません。 より大きな取り組みは、≤10issueの連続したマイルストーンに分割され、各々が独立して価値があり、デプロイ可能です。

マイルストーン間: 停止して監査してください。前のマイルストーンはその目標を達成しましたか？ デザイン仮定はまだ有効ですか？ 明示的なユーザー承認なしに、1セッションで複数のマイルストーンを実行しないでください。

Issue サイズチェック

issueをファイルする前に、PRサイズを推定してください。実装が明らかに400行を超える差分:

1. 自然な分割ポイントを特定します
2. 代わりに2～3つの小さいissueをファイルします
3. これらの間に依存関係を設定します

8つのファイルにタッチする600行のPRは、issueが大きすぎたことの兆候です。実装が正しく行われたことではありません。

マイルストーンテンプレート

## Milestone N: [Name]

Goal: [1文 — このマイルストーンが何をデリバーするか]

Issues:
1. #N — [title]
2. #N — [title]
...

Audit gate: マイルストーンN+1を開始する前に、確認します:
- [ ] すべてのマイルストーンNのissueがクローズされています
- [ ] [特定の動作]がエンドツーエンドで動作していることが確認されています
- [ ] [エリア]で回帰がありません

---

依存関係宣言

issueの順序を暗黙的なままにしないでください。issueB がissueAがマージされるまで開始できない場合は、issueボディとGitHubでそう述べてください:

## Dependencies

- Blocked by: #42 (古いものを削除する前に新しいインターフェースが存在する必要があります)
- Blocks: #44 (このAPIが安定するまでダウンストリームユーザーを更新できません)

これをGitHubでも設定します:

# GitHub doesn't have native blocking, use labels or project board ordering
gh issue edit <N> --add-label "blocked"
gh issue comment <N> --body "Blocked by #42 — will start after that merges."

削除の前に追加 はマイルストーンが両方を含む場合の推奨される順序です。古いコードを最初に削除してください — テストは壊れます — その後新しいコードを追加してください — テストは合格します。これにより、shimを追加することで削除issueを閉じることが不可能になります。

---

構造的受け入れ基準

2つの実装が構造的に整列する必要があるissue（例: 「関数Aを関数Bと一貫性を持たせる」）の場合、動作基準は十分ではありません。issueは以下を指定する必要があります:

1. 比較するファイルと関数 — 正確なパスと関数名
2. 一致する必要がある構造プロパティ — 「同じ動作」ではなく「同じDAG構築アプローチ」、「同じループ順序」、「同じエッジインターリーブ」
3. 確認方法 — diffコマンドまたは実装者が完了を宣言する前に実行する必要がある明示的な比較

なぜこれが重要か: プライマリエージェントはissueをそのままサブエージェントの実装に渡します。構造プロパティが曖昧に説明されている場合、サブエージェントはそれの彼らの解釈を実装します。彼らの解釈はすべてのテストに合格しながら、バグを引き起こした1つの構造的な違いを見逃す可能性があります。

## Acceptance Criteria

- [ ] `verify_hints_acyclic`は繰り返す前に事前構築された完全なグラフ
  （すべてのペア）を使用して基本DAGを構築します — `_simulate_hints_sequential`
  行42～67と同一です。両方の関数を読み、DAG構築ブロックが両方のペアイテレーションループの前に来ることを確認することで確認します。
- [ ] `verify_hints_acyclic`対`_simulate_hints_sequential`のdiffはDAG構築に構造的な違いがないことを示します（変数名のみが異なることがあります）

動作基準のみ（不十分）:

"verify_hints_acyclicを_simulate_hints_sequentialと一貫性を持たせる"

構造的基準（十分）:

"verify_hints_acyclicは_simulate_hints_sequential行42～67と同じようにテストするすべてのヒントの前に、すべてのペアから完全なcommit順序ベースDAGを事前構築する必要があります。確認: verify_hints_acyclicのペアループは、ペアごとにインクリメンタルに構築するのではなく、事前構築されたDAGを受け取る必要があります。」

Issue は委譲プロンプトです

実装者はこのissueを逐語的に — ボディとすべてのコメント — 受け取り、直接実装します。プライマリエージェントは再説明または言い換えを行いません。受け入れ基準は、実装プロンプトを書いているかのように書いてください。なぜなら、あなたはそうだからです。重要なすべての構造的詳細はissueボディまたはピン留めコメントに含まれている必要があります。委譲時に追加される口頭説明ではなく。

委譲するときは常にコメントを含めます:

gh issue view <N>         # body
gh issue view <N> --comments   # full discussion thread

コメントスレッドで行われた設計上の決定 — 明確化、オプション選択、「オプション1を使用、オプション2ではない」を含む — は仕様の一部です。ボディのみを読む実装者はissueの半分を見逃します。

---

アンチパターン

• 「X を追加して Y を削除」 を1つのissueで — 削除は延期されます、確実に
• 曖昧な受け入れ基準 — 「パフォーマンスを改善」は検証不可です；「ロードテスト下でp95レイテンシ < 200ms」です
• 構造的整列のための動作基準 — 「Aを Bと一貫性を持たせる」は一致する必要がある構造プロパティと確認方法を指定する必要があります
• スコープ外がない — これなしでは、スコープ拡大はレビューまで見えません
• 削除issueの確認コマンドがない — issueは古いコードがまだ存在したまま「クローズ」できます
• 「必要に応じてテスト」 — 常に指定します；「必要に応じて」は決してを意味します
• サイレント設計ドキュメント競合 — 仕様から逸脱して注記せずに、隠れた技術的負債を生成します
• メガissue — 1つの集中したPRで実装できない場合、2つのissueです