| 1 | # Agent-Ready Issues |
| 2 | |
| 3 | CodeWhale's tracker is worked by humans and by autonomous agents. An issue is |
| 4 | **agent-ready** when a fresh agent — with a clone of `main`, shell/read/write |
| 5 | tools, and *no other context* — can execute it end-to-end and prove the result. |
| 6 | This document defines that standard for new issues, for triage reworks of |
| 7 | existing issues, and for maintainer replies on community threads. |
| 8 | |
| 9 | The filing-time version of this standard is the |
| 10 | [Agent task issue form](../.github/ISSUE_TEMPLATE/agent-task.yml). This page |
| 11 | extends it to the rest of the tracker. |
| 12 | |
| 13 | ## Source of truth |
| 14 | |
| 15 | - The **active milestone** decides what lane an issue is in. Version labels |
| 16 | (`v0.9.2`, `v0.9.3`, …) are historical metadata; they never choose or change |
| 17 | a milestone. |
| 18 | - The **issue body** is the executable spec. Refinements that arrive as |
| 19 | comments get folded into the body during triage so the body never lies. |
| 20 | - Queue order within a lane (from `AGENTS.md`): release blockers, recently |
| 21 | approved PRs, clean small PRs, blocked PRs with obvious fixes, safely |
| 22 | harvestable dirty PRs, then larger architecture work. |
| 23 | |
| 24 | ## Required structure |
| 25 | |
| 26 | ```markdown |
| 27 | ## Problem |
| 28 | 2–6 sentences. What is wrong or missing, and why it matters now. |
| 29 | |
| 30 | ## Current evidence |
| 31 | Verified anchors and observed behavior, e.g. |
| 32 | `crates/tui/src/model_routing.rs::provider_router_candidates`. |
| 33 | |
| 34 | ## Scope |
| 35 | Numbered steps; one concrete action per step, file paths where known. |
| 36 | |
| 37 | ## Key files |
| 38 | One verified path per line. The executing agent reads these first. |
| 39 | |
| 40 | ## Acceptance criteria |
| 41 | Behavior-level `- [ ]` checkboxes. Every item must be testable. |
| 42 | |
| 43 | ## Verification |
| 44 | Exact commands, e.g. |
| 45 | `cargo test -p codewhale-tui --bin codewhale-tui --locked <filter>`. |
| 46 | |
| 47 | ## Out of scope |
| 48 | What this issue deliberately does not change. |
| 49 | |
| 50 | ## Related |
| 51 | Real issue/PR numbers only, each with one line on the boundary between them. |
| 52 | ``` |
| 53 | |
| 54 | Epics additionally get a `## Phases` section: each phase sized as one |
| 55 | agent-executable slice with its own acceptance bullet. An epic without phases |
| 56 | is not agent-ready. |
| 57 | |
| 58 | ## Anchor discipline |
| 59 | |
| 60 | - Every file path, symbol, config key, and command in an issue body must be |
| 61 | verified against the current tree before it is written down. `rg`/`ls` |
| 62 | first, then cite. |
| 63 | - If something cannot be located, write |
| 64 | `(anchor not found — needs discovery)` rather than a guess. A wrong anchor |
| 65 | costs an executing agent more than a missing one. |
| 66 | - Verification commands use real workspace package names |
| 67 | (`codewhale-tui`, `codewhale-config`, `codewhale-protocol`, …) — confirm in |
| 68 | the crate's `Cargo.toml`, not from memory. |
| 69 | |
| 70 | ## Reworking existing issues |
| 71 | |
| 72 | - **Maintainer-authored issues**: restructure the body in place. Preserve |
| 73 | every constraint and concrete fact from the original; fold in refinements |
| 74 | from comments; end the body with a dated triage note, e.g. |
| 75 | `_Triage note: body restructured for agent execution on YYYY-MM-DD; prior |
| 76 | comment refinements folded in. Original wording preserved in edit history._` |
| 77 | - **Community-authored issues**: never rewrite the reporter's body. Post a |
| 78 | maintainer comment carrying the same skeleton instead — status in the lane, |
| 79 | what a fix looks like (anchored bullets + acceptance criteria), and the |
| 80 | smallest set of asks that unblocks the issue. |
| 81 | - Apply the `agent-ready` label only when the body (or, for community issues, |
| 82 | body + maintainer deconstruction comment) genuinely meets this standard. |
| 83 | The label is a gate, not a wish. |
| 84 | |
| 85 | ## Community thread etiquette |
| 86 | |
| 87 | - Open with specific thanks that references a real detail of the report — |
| 88 | proof it was read. Vary phrasing across issues. |
| 89 | - State status honestly: milestone lane, what already shipped (cite the |
| 90 | version, PR, or commit — only with evidence), and what is blocking. |
| 91 | - Never claim testing or reproduction that did not happen; never promise |
| 92 | dates. "Queued in the v0.9.2 release lane" is the honest formulation. |
| 93 | - Reporters writing in Chinese (or another language) get the key points and |
| 94 | asks translated at the end of the English reply. |
| 95 | - `needs-info` issues get exactly one crisp ask (typically |
| 96 | `codewhale --version`, `codewhale doctor --json`, OS + terminal, minimal |
| 97 | repro), plus a pointer that the stale policy in |
| 98 | [ISSUE_TRIAGE.md](./ISSUE_TRIAGE.md) applies once a maintainer labels the |
| 99 | issue `needs-info`. |
| 100 | |
| 101 | ## Why this exists |
| 102 | |
| 103 | A deconstructed issue is cheap to execute and cheap to verify: the researcher |
| 104 | pays the discovery cost once, at triage time, instead of every executing agent |
| 105 | paying it again. When an issue is agent-ready, "pick up the next item in the |
| 106 | milestone" becomes a safe instruction for any contributor — human or agent. |
| 107 |