Wayfinder map: autonomic issue-fixing agents

[chiptus]

Destination

A complete spec + playbook for an autonomic issue pipeline: docs/agents/autonomic-issues.md (pipeline design, quality gates, guardrails) plus paste-ready Claude Code Routine prompt(s). Agents triage the backlog and turn ready-for-agent issues into green, tested, self-reviewed PRs so the maintainer only reviews. Setting up the Routine itself is a deliberate manual act after this map closes.

Notes

Domain: agent orchestration over this repo's GitHub issue tracker (docs/agents/issue-tracker.md, docs/agents/triage-labels.md). Sessions working tickets should consult the writing-for-agents skill when drafting the playbook/prompts, and grilling + domain-modeling for HITL tickets.

Standing decisions from charting:

• Runtime: Claude Code Routines spawning fresh remote sessions. Daily cadence; skip/shrink the firing when ~2–3 agent PRs are already open awaiting review.
• Scope: triage needs-triage/unlabeled issues AND implement ready-for-agent ones. needs-triage + unlabeled is the only intake queue: needs-info issues are fully inert to agents (no scanning for new comments — after answering, the maintainer flips the label back to needs-triage). Also off-limits: wayfinder:* tickets, ready-for-human, wontfix.
• Quality gates (all four): tests for the change (test-less only for pure chores); local lint + unit (+ affected integration) pass before every push; CI green and review-bot findings addressed; a self code-review pass on the diff before flagging for review.
• Guardrails: never close issues — but the triage agent does directly apply wontfix / ready-for-human labels with a comment explaining why (labels are reversible; closing is the maintainer's). Never add the staging label; never merge PRs; never supabase db push/db reset. Otherwise permissive: migration files, workflow edits, and small product judgment calls are allowed — the PR review is the safety net.
• Notifications: routine completion push when a firing produced something (PR ready, triage questions); silent otherwise.

Decisions so far

• Routine mechanics for the autonomic pipeline: Routines support the design — fresh-session firings clone the repo (CLAUDE.md/skills load) and run fully autonomously; per-routine model selection allows a cheap-triage/expensive-fix split; push notifications are noteworthy-only so no-op firings stay silent; min cadence 1h; but firings can overlap with no mutual exclusion, so the PR cap must be enforced in-prompt by counting open claude/ PRs at run start. Findings: docs/research/routine-mechanics.md.
• Triage rubric: what makes an issue ready-for-agent: four required criteria (determinable done-ness, reproducible/locatable, self-contained, reviewable-from-diff) — missing the first two → needs-info with numbered one-line-answerable questions; missing the last two → ready-for-human. Triage applies wontfix/ready-for-human labels itself with a why-comment (never closes), may create sub-issues to split oversized work, writes inferred specs as comments (never body edits), and may apply category labels.

Not yet specified

• Model and budget choice per firing; whether triage and fix use different models (per-routine model selection confirmed possible — the choice itself is still open).
• What a firing does with a stale agent PR from a previous firing (rebase onto main? ping? count against the cap forever?). Touches the coordination ticket but may outgrow it.
• Extending the pipeline to external-PR triage (issue-tracker.md already treats PRs as a request surface).
• A repo steward skill (.claude/skills/steward/) so any session driving agent PRs shares conventions.
• Learning loop: how recurring review feedback from the maintainer gets folded back into the playbook/prompts over time.

Out of scope

• Actually creating the Routine(s) — deliberate manual setup after the map closes.
• Driving PRs through the maintainer's own review comments to merge; the pipeline stops at "green, tested, self-reviewed, awaiting review".
• A GitHub Actions–based runner (Routines chosen instead).