From 79665e34856df6f98edb5b7dfcc061bc60be0361 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 06:41:59 +0000 Subject: [PATCH 1/3] docs(autonomic-issues): add epic label for fully-split tracking issues Lets triage recognize an already-split tracking parent and self-label it `epic` (skipped by intake thereafter) instead of re-triaging it from comment history each sweep. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01Pp8kfg4yZ4nhuhEDGvFb4S --- docs/agents/autonomic-issues.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/agents/autonomic-issues.md b/docs/agents/autonomic-issues.md index 50267cc2..f4c7fee9 100644 --- a/docs/agents/autonomic-issues.md +++ b/docs/agents/autonomic-issues.md @@ -20,7 +20,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,7 +37,8 @@ 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 of the split work has its own sub-issue carrying a state label, apply `epic` to the parent (dropping any state role it had) and drop it out of future intake — it stays open purely as a tracker until the maintainer closes it. +- **`epic` recognition**: an issue that reads as unlabeled/`needs-triage` but turns out, on inspection, to already be a fully-split tracking parent (sub-issues exist and each carries its own state label; the parent has no independent work left) just gets the `epic` label applied directly — no comment, no maintainer confirmation, since the label only describes a structural fact that's already visible in the sub-issue list, not a new verdict on the work. - **`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. From e7dfd8ec734604c305f9342f8f0c6db90504243d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 06:44:27 +0000 Subject: [PATCH 2/3] docs(autonomic-issues): dedupe epic-label recognition rule, add to setup checklist The rubric had two bullets stating the same "sub-issues already carry state labels" recognition criterion; merge them into one. Also list `epic` among the labels the setup checklist says to create. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01Pp8kfg4yZ4nhuhEDGvFb4S --- docs/agents/autonomic-issues.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/agents/autonomic-issues.md b/docs/agents/autonomic-issues.md index f4c7fee9..42d5c85f 100644 --- a/docs/agents/autonomic-issues.md +++ b/docs/agents/autonomic-issues.md @@ -37,8 +37,7 @@ 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. Once every piece of the split work has its own sub-issue carrying a state label, apply `epic` to the parent (dropping any state role it had) and drop it out of future intake — it stays open purely as a tracker until the maintainer closes it. -- **`epic` recognition**: an issue that reads as unlabeled/`needs-triage` but turns out, on inspection, to already be a fully-split tracking parent (sub-issues exist and each carries its own state label; the parent has no independent work left) just gets the `epic` label applied directly — no comment, no maintainer confirmation, since the label only describes a structural fact that's already visible in the sub-issue list, not a new verdict on the work. +- **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 of the split work has its own sub-issue carrying a state label, the parent is an **epic**: apply the `epic` label (dropping any state role it had) and it drops out of future intake, staying open purely as a tracker until the maintainer closes it. Recognizing this needs no comment or maintainer confirmation, on first encounter or on a later sweep that finds the label still missing — `epic` only names a structural fact already visible in the sub-issue list, not a new verdict on the work. - **`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. @@ -81,7 +80,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: `agent:wip`, `agent:pr`, `epic`, `priority:high`, `priority:low` (triage vocabulary from `docs/agents/triage-labels.md` plus `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. From 1b36539464b930f70ea1548354e9aa5f1668975f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 31 Aug 2026 06:53:19 +0000 Subject: [PATCH 3/3] docs(agents): make triage-labels.md the single label dictionary triage-labels.md now documents every label the autonomic pipeline reads or writes (canonical triage roles, agent:/priority:/epic/ wayfinder: pipeline labels, categories) with a meaning and an applied-by column, addressing PR feedback that epic wasn't discoverable from the doc that claims to be "the label vocabulary". autonomic-issues.md now points to that dictionary for label meaning instead of restating it inline, keeping only the pipeline mechanics (when/how each label gets applied) and dropping a couple of sentences that duplicated the Fix firing steps. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01Pp8kfg4yZ4nhuhEDGvFb4S --- docs/agents/autonomic-issues.md | 11 ++++------- docs/agents/triage-labels.md | 24 ++++++++++++++++++++++-- 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/agents/autonomic-issues.md b/docs/agents/autonomic-issues.md index 42d5c85f..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. @@ -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. Once every piece of the split work has its own sub-issue carrying a state label, the parent is an **epic**: apply the `epic` label (dropping any state role it had) and it drops out of future intake, staying open purely as a tracker until the maintainer closes it. Recognizing this needs no comment or maintainer confirmation, on first encounter or on a later sweep that finds the label still missing — `epic` only names a structural fact already visible in the sub-issue list, not a new verdict on the work. +- **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`, `epic`, `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.