From 129fd88ca2696b71d2b04e293a57503757fd0db9 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 19:05:36 +0000 Subject: [PATCH 1/2] docs: codify the agent-ready issue standard Capture the deconstruction convention the tracker already trends toward (.github/ISSUE_TEMPLATE/agent-task.yml) as a triage standard for existing issues: required body structure, anchor discipline, epic phasing, the maintainer-vs-community rework boundary, and community thread etiquette. Link it from AGENTS.md stewardship guidance and docs/ISSUE_TRIAGE.md so future triage rounds apply one standard. Written during the 2026-07-18 v0.9.2 lane triage round with agent assistance. --- AGENTS.md | 4 ++ docs/AGENT_READY_ISSUES.md | 106 +++++++++++++++++++++++++++++++++++++ docs/ISSUE_TRIAGE.md | 5 ++ 3 files changed, 115 insertions(+) create mode 100644 docs/AGENT_READY_ISSUES.md diff --git a/AGENTS.md b/AGENTS.md index c23c2eab9d..65ce2437cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,10 @@ - Review PRs from code, tests, linked issues, comments, and check results — let those, rather than the title or labels alone, drive every merge, close, harvest, or defer decision on community work. +- Triage issues toward the agent-ready standard in + `docs/AGENT_READY_ISSUES.md`: maintainer-authored bodies get restructured + into executable specs with verified anchors; community-authored issues get a + maintainer deconstruction comment instead of a body rewrite. - Respect concurrent work in the tree — leave unrelated edits by other people or agents intact. diff --git a/docs/AGENT_READY_ISSUES.md b/docs/AGENT_READY_ISSUES.md new file mode 100644 index 0000000000..be6e13177a --- /dev/null +++ b/docs/AGENT_READY_ISSUES.md @@ -0,0 +1,106 @@ +# Agent-Ready Issues + +CodeWhale's tracker is worked by humans and by autonomous agents. An issue is +**agent-ready** when a fresh agent — with a clone of `main`, shell/read/write +tools, and *no other context* — can execute it end-to-end and prove the result. +This document defines that standard for new issues, for triage reworks of +existing issues, and for maintainer replies on community threads. + +The filing-time version of this standard is the +[Agent task issue form](../.github/ISSUE_TEMPLATE/agent-task.yml). This page +extends it to the rest of the tracker. + +## Source of truth + +- The **active milestone** decides what lane an issue is in. Version labels + (`v0.9.2`, `v0.9.3`, …) are historical metadata; they never choose or change + a milestone. +- The **issue body** is the executable spec. Refinements that arrive as + comments get folded into the body during triage so the body never lies. +- Queue order within a lane (from `AGENTS.md`): release blockers, recently + approved PRs, clean small PRs, blocked PRs with obvious fixes, safely + harvestable dirty PRs, then larger architecture work. + +## Required structure + +```markdown +## Problem +2–6 sentences. What is wrong or missing, and why it matters now. + +## Current evidence +Verified anchors and observed behavior, e.g. +`crates/tui/src/model_routing.rs::provider_router_candidates`. + +## Scope +Numbered steps; one concrete action per step, file paths where known. + +## Key files +One verified path per line. The executing agent reads these first. + +## Acceptance criteria +Behavior-level `- [ ]` checkboxes. Every item must be testable. + +## Verification +Exact commands, e.g. +`cargo test -p codewhale-tui --bin codewhale-tui --locked `. + +## Out of scope +What this issue deliberately does not change. + +## Related +Real issue/PR numbers only, each with one line on the boundary between them. +``` + +Epics additionally get a `## Phases` section: each phase sized as one +agent-executable slice with its own acceptance bullet. An epic without phases +is not agent-ready. + +## Anchor discipline + +- Every file path, symbol, config key, and command in an issue body must be + verified against the current tree before it is written down. `rg`/`ls` + first, then cite. +- If something cannot be located, write + `(anchor not found — needs discovery)` rather than a guess. A wrong anchor + costs an executing agent more than a missing one. +- Verification commands use real workspace package names + (`codewhale-tui`, `codewhale-config`, `codewhale-protocol`, …) — confirm in + the crate's `Cargo.toml`, not from memory. + +## Reworking existing issues + +- **Maintainer-authored issues**: restructure the body in place. Preserve + every constraint and concrete fact from the original; fold in refinements + from comments; end the body with a dated triage note, e.g. + `_Triage note: body restructured for agent execution on YYYY-MM-DD; prior + comment refinements folded in. Original wording preserved in edit history._` +- **Community-authored issues**: never rewrite the reporter's body. Post a + maintainer comment carrying the same skeleton instead — status in the lane, + what a fix looks like (anchored bullets + acceptance criteria), and the + smallest set of asks that unblocks the issue. +- Apply the `agent-ready` label only when the body (or, for community issues, + body + maintainer deconstruction comment) genuinely meets this standard. + The label is a gate, not a wish. + +## Community thread etiquette + +- Open with specific thanks that references a real detail of the report — + proof it was read. Vary phrasing across issues. +- State status honestly: milestone lane, what already shipped (cite the + version, PR, or commit — only with evidence), and what is blocking. +- Never claim testing or reproduction that did not happen; never promise + dates. "Queued in the v0.9.2 release lane" is the honest formulation. +- Reporters writing in Chinese (or another language) get the key points and + asks translated at the end of the English reply. +- `needs-info` issues get exactly one crisp ask (typically + `codewhale --version`, `codewhale doctor --json`, OS + terminal, minimal + repro), plus a pointer that the stale policy in + [ISSUE_TRIAGE.md](./ISSUE_TRIAGE.md) applies once a maintainer labels the + issue `needs-info`. + +## Why this exists + +A deconstructed issue is cheap to execute and cheap to verify: the researcher +pays the discovery cost once, at triage time, instead of every executing agent +paying it again. When an issue is agent-ready, "pick up the next item in the +milestone" becomes a safe instruction for any contributor — human or agent. diff --git a/docs/ISSUE_TRIAGE.md b/docs/ISSUE_TRIAGE.md index 2b4126780c..8f1fd70352 100644 --- a/docs/ISSUE_TRIAGE.md +++ b/docs/ISSUE_TRIAGE.md @@ -1,5 +1,10 @@ # Issue Triage +Triage aims issues at the agent-ready standard defined in +[AGENT_READY_ISSUES.md](./AGENT_READY_ISSUES.md): bodies that a fresh agent +can execute without extra context. This page covers the stale/`needs-info` +lifecycle that runs alongside that standard. + ## Stale `needs-info` cleanup The stale workflow only acts on issues that a maintainer has explicitly labeled From 842591e08f54bfa6c641116c9e884f704e26cf2d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 22:21:33 +0000 Subject: [PATCH 2/2] docs(keybindings): mark the Windows CSI-u push note as superseded The v0.8.29 audit note documents writing \x1b[>1u directly on Windows as current behavior, but push_keyboard_enhancement_flags now probes with \x1b[>0u and enables no flags, decoding newline chords per terminal instead. Found while triaging #1687, where the stale note pointed at the wrong mechanism. Noted during the 2026-07-18 triage round with agent assistance. --- docs/KEYBINDINGS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/KEYBINDINGS.md b/docs/KEYBINDINGS.md index 16b2c82f3b..205c892b1e 100644 --- a/docs/KEYBINDINGS.md +++ b/docs/KEYBINDINGS.md @@ -163,7 +163,8 @@ tmux's `load-buffer -w` path when running inside tmux. ## v0.8.29 audit notes -- **`Shift+Enter` / `Alt+Enter` newlines now work in VSCode on Windows (#1359).** crossterm's `PushKeyboardEnhancementFlags` command unconditionally returns `Unsupported` on Windows (`is_ansi_code_supported() == false`), so the Kitty keyboard protocol escape was never written to the terminal. Without it, VSCode's xterm.js stays in legacy mode where `Shift+Enter` is indistinguishable from plain `Enter`, causing the composer to send the message instead of inserting a newline. The fix writes the push/pop escapes (`\x1b[>1u` / `\x1b[<1u`) directly on Windows, bypassing crossterm's capability gate. VSCode integrated terminal and Windows Terminal ≥1.17 both honour the Kitty keyboard protocol; terminals that do not understand the sequences silently discard them. +- **`Shift+Enter` / `Alt+Enter` newlines now work in VSCode on Windows (#1359).** crossterm's `PushKeyboardEnhancementFlags` command unconditionally returns `Unsupported` on Windows (`is_ansi_code_supported() == false`), so the Kitty keyboard protocol escape was never written to the terminal. Without it, VSCode's xterm.js stays in legacy mode where `Shift+Enter` is indistinguishable from plain `Enter`, causing the composer to send the message instead of inserting a newline. The fix wrote the push/pop escapes (`\x1b[>1u` / `\x1b[<1u`) directly on Windows, bypassing crossterm's capability gate. VSCode integrated terminal and Windows Terminal ≥1.17 both honour the Kitty keyboard protocol; terminals that do not understand the sequences silently discard them. + - *Superseded:* current builds probe the protocol without enabling any flags on Windows — `push_keyboard_enhancement_flags` in `crates/tui/src/tui/ui.rs` writes `\x1b[>0u` (flag value `0`), so modified keys are no longer delivered CSI-u-encoded; newline chords are decoded per terminal via `is_composer_newline_key`. ## v0.8.13 audit notes