diff --git a/docs/agents/autonomic-issues.md b/docs/agents/autonomic-issues.md index 50267cc2..9bbfa1aa 100644 --- a/docs/agents/autonomic-issues.md +++ b/docs/agents/autonomic-issues.md @@ -6,10 +6,7 @@ The paste-ready Routine prompts are at the [bottom of this doc](#routine-prompts ## Shared state: the `agent:` labels -In-flight state lives as labels **on issues**; an issue's label tells any fresh firing where it is in the pipeline. - -- `agent:wip` — an agent has claimed the issue this firing. Applied with a claim comment (timestamped, naming the branch) as the fix worker's first act after picking, before any work. -- `agent:pr` — an agent PR for this issue is awaiting review. On opening the PR, swap the issue's `agent:wip` to `agent:pr` and label the PR itself `agent:pr` too. Merging the PR closes the issue via `Closes #N`, which drops it out of every count automatically. +In-flight state lives as labels **on issues**; an issue's label tells any fresh firing where it is in the pipeline. Meaning and who applies each: `docs/agents/triage-labels.md`. Application mechanics (claim comment, PR swap) are in the Fix firing steps below. Merging a PR closes its issue via `Closes #N`, which drops it out of every count automatically. **The PR cap**: at run start the fix worker counts open issues labeled `agent:pr` (one search: `is:issue is:open label:agent:pr`). At or above **3**, the review queue is full — end silently. Counting issues rather than PRs stays correct even if a PR-side label is forgotten. Firings can overlap with no mutual exclusion, so this in-prompt count is the enforcement; a rare overshoot-by-one is accepted. @@ -20,7 +17,7 @@ In-flight state lives as labels **on issues**; an issue's label tells any fresh ## Triage firing 1. **Release stale claims** (above). -2. **Intake queue**: open issues labeled `needs-triage` plus open unlabeled issues — nothing else. Skip `wayfinder:*` tickets. `needs-info` issues are fully inert: after the reporter answers, the maintainer flips the label back to `needs-triage`. Empty queue → end silently. +2. **Intake queue**: open issues labeled `needs-triage` plus open unlabeled issues — nothing else. Skip `wayfinder:*` and `epic` tickets. `needs-info` issues are fully inert: after the reporter answers, the maintainer flips the label back to `needs-triage`. Empty queue → end silently. 3. **Apply the rubric** (below) to each intake issue **through the triage skill**: Read `.claude/skills/triage/SKILL.md` directly and follow it (it is not model-invocable, so the Skill tool won't list it). It carries the tracker mechanics — the AI-disclaimer prefix on every posted comment, the agent-brief format for `ready-for-agent` issues, the out-of-scope knowledge base. This doc's rubric and guardrails win wherever the two differ. 4. **Summary table**: end the session with a markdown table of the sweep — one row per issue looked at, `issue | verdict | one-line reason` (verdicts: the label applied, or "held" / "skipped" with why). This is transcript output only, not a GitHub write. @@ -37,11 +34,11 @@ All four hold → label `ready-for-agent`. Missing (a)/(b) → `needs-info`. Mis - **`needs-info` questions**: 2–3 numbered questions in one comment, each answerable in one line and each stating why it blocks ("can't reproduce without…"), so the maintainer answers inline in a single reply. - **`ready-for-human` routes**: the work needs access the agent lacks (GitHub settings, Supabase dashboard, third-party consoles), or the deliverable is a maintainer decision rather than code. Security-sensitive code stays agent-eligible; size alone never routes to human. -- **Oversized issues**: no hard size cap — flag "too big for one firing" with a proposed split as a comment, and optionally create the child sub-issues directly. Leave the parent open; the work becomes takeable only once split. +- **Oversized issues**: no hard size cap — flag "too big for one firing" with a proposed split as a comment, and optionally create the child sub-issues directly. Leave the parent open; the work becomes takeable only once split. Once every piece is its own sub-issue carrying a state label, the parent has become an `epic` (see `docs/agents/triage-labels.md`): apply the label directly, dropping any state role it had — no comment or maintainer confirmation needed, whether that's on first encounter or a later sweep that finds the label still missing. - **`wontfix` / duplicates**: apply `wontfix` or `ready-for-human` directly, with a comment explaining why. A duplicate recommendation always names the surviving issue. Only the maintainer closes issues. - **Spec gaps**: issue bodies belong to their authors — write an inferred spec as a comment instead, and when that comment supplies the missing spec, label `ready-for-agent` in the same pass. Provenance stays clear. - **Category labels**: apply ordinary labels (`bug`, `enhancement`, `refactor`, `chore`) where obvious. -- **Priority is the maintainer's steering wheel**: `priority:high` and `priority:low` are maintainer-applied only — triage never sets them. +- **Priority is the maintainer's steering wheel**: triage never sets `priority:high`/`priority:low` (see `docs/agents/triage-labels.md`). ## Fix firing @@ -80,7 +77,7 @@ Both routines run with push notifications on. The platform sends a push only whe ## Setup checklist (manual, one-time) -1. Create the labels: `agent:wip`, `agent:pr`, `priority:high`, `priority:low` (triage vocabulary from `docs/agents/triage-labels.md` plus `bug`/`enhancement`/`chore` should already exist). +1. Create the labels in `docs/agents/triage-labels.md`'s pipeline-labels table (`agent:wip`, `agent:pr`, `epic`, `priority:high`, `priority:low`) plus the five canonical triage-role labels — `bug`/`enhancement`/`chore` should already exist. 2. Create the **triage** Routine: daily, Sonnet (a test firing showed Haiku mis-triages — it judges from issue text alone instead of verifying premises in the codebase), this repo only, Default (trusted-network) environment, no connectors beyond GitHub, push notifications on, prompt below. 3. Create the **fix** Routine: daily ~1h after triage, stronger model, same scoping, push notifications on, prompt below. 4. Routine prompts stay short pointers — evolve the pipeline by editing this doc via PR, not the Routine form. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index b716855d..dec98deb 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -1,6 +1,10 @@ # Triage Labels -The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. +Every label the autonomic issue pipeline reads or writes, what it means, and who's allowed to apply it. + +## Canonical triage-role labels + +The skills speak in terms of five canonical triage roles. This table maps those roles to the actual label strings used in this repo's issue tracker. | Label in mattpocock/skills | Label in our tracker | Meaning | | -------------------------- | -------------------- | ---------------------------------------- | @@ -10,6 +14,22 @@ The skills speak in terms of five canonical triage roles. This file maps those r | `ready-for-human` | `ready-for-human` | Requires human implementation | | `wontfix` | `wontfix` | Will not be actioned | -When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. +When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. Applied by: the triage firing, via the triage skill. Edit the right-hand column to match whatever vocabulary you actually use. + +## Pipeline labels + +Repo-specific labels the autonomic pipeline (`docs/agents/autonomic-issues.md`) uses outside the five canonical roles above — not part of the mattpocock/skills vocabulary, so a skill invocation won't look for them here. + +| Label | Meaning | Applied by | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| `epic` | Tracking-only parent issue whose work has already been fully split into sub-issues, each carrying its own state label. Stays open only to track them; excluded from triage intake. | Triage firing — self-service, no maintainer confirmation needed | +| `agent:wip` | An agent has claimed the issue this firing. | Fix firing | +| `agent:pr` | An agent PR for this issue is awaiting review. | Fix firing (swapped from `agent:wip` on opening the PR) | +| `priority:high` / `priority:low` | Steers fix-firing pick order. | Maintainer only — triage and fix never set these | +| `wayfinder:*` | Belongs to a separate design/spec workflow, not this pipeline. | Never by this pipeline — triage skips these tickets entirely | + +## Category labels + +`bug`, `enhancement`, `chore`, `refactor` — applied where obvious; self-explanatory, not part of either table above.