work-backlog

What this skill does

# Work Backlog

Make progress on a Steward backlog: tend the PRs already in flight, start new items, keep each linked PR moving toward merge-ready, and dismiss items whose work is already done. The skill is **stateless** — every run is configured entirely by its arguments, never by saved state, so different people can run it different ways at different times.

## Modes of Invocation

Route on whether the user passed an argument:

- **No argument → Conversational session.** Show the current backlog, ask what they want to accomplish, do the agreed work, and end by emitting the exact command to schedule as a nightly routine. This is the guided, discover-by-talking entry point (the same shape as `/steward:define-steward`).
- **Argument(s) given → Direct run, no conversation.** Parse the arguments into a run config and execute. This is what an unattended nightly Claude Code Routine calls, and what the heartbeat email's one-paste command uses. Three argument shapes:
  - **A specific item** — an id, group id, or human-readable reference. Work that one item.
  - **A steward** — a steward name or id. Work that steward's top eligible item.
  - **Batch params** — a max item count and/or scope and/or autonomy (e.g. `--max-items 3 --steward accessibility --autonomy pr`, or natural language like "work 3 accessibility items, open PRs, don't merge"). Run a batch session.

If an argument is ambiguous between shapes (a name that could be a steward or an item), resolve it with `list_stewards` and `list_steward_backlog_items` before acting; ask only if it stays ambiguous.

## Run Config (the parameters)

Every direct run resolves to these. The conversational session fills them by asking; a routine command sets them explicitly. There is no persisted profile — the command line is the entire config.

- **scope** — repository-wide (default), a single `--steward <name|id>`, or a single named item.
- **max-items** — how many items the run may work before stopping (default **3** for a batch; exactly **1** for a single named item). Bounds an unattended run so a cron can't run unbounded.
- **autonomy** — how far each item goes:
  - `pr` (**default, and the only safe default for an unattended run**): implement, open a linked PR, stop. A human merges.
  - `merge`: additionally merge a PR once it is green and review-clean. Opt-in, higher trust — never the default for a routine that runs while the user is asleep.

## Conversational Session (no arguments)

1. Show the current backlog up front so the conversation is grounded: call `list_stewards` (pass `repository`) for queued/in-flight/done counts per steward, and note any in-flight backlog PRs. Lead with this, not with questions.
2. Ask what they want to accomplish, mapping their answer onto the run config: **scope** (whole repo, one steward, one item?), **how much** (how many items, or "just the top one"?), **autonomy** (open PRs and stop, or also merge what's green?). Keep it to the few questions that actually change the run; infer sane defaults for the rest and state them.
3. Run the agreed work using the **Direct Run** sections below (single item or batch).
4. **End by emitting the nightly routine command** — see **Emitting the Routine Command**. The point of the conversation is not just to do tonight's work; it is to hand the user the reproducible command so they can schedule it and stop typing it.

## Reconciliation (always on, both modes)

Backlog items go stale: the work gets done by other changes before the item is worked. Catching this is cheap here (you have the repo and the diffs) and expensive anywhere else, so it is a standing part of every run, not a flag.

- **Before implementing any claimed item**, verify the work is not already done. Check recent merged PRs, `git log`, and the actual current code for the item's objective. If the objective is already satisfied, do **not** implement or open a PR — `dismiss` the item with `manage_backlog_work` and a concrete, evidence-backed note naming what already did the work (the commit/PR), and move on.
- **When tending an in-flight PR** (see batch session) you find merge conflicts or staleness, and resolving them reveals the work was superseded by more recent changes, treat that as the same signal: dismiss the backlog item with evidence and surface the PR as one to **close, not merge** (do not close someone's PR autonomously — flag it in the report as a decision for the user).
- Never dismiss on a fuzzy hunch. Dismissal requires a specific artifact (a merged PR, a commit, code that already implements the objective). When unsure, leave the item and note the uncertainty in the report.

## Direct Run — Single Item (a specific item or a steward's top item)

This is the original single-item behavior and the path the heartbeat email's one-paste command uses.

### Selecting the item
- **Specific item.** If you have an id or unambiguous reference, use it directly. For a fuzzy reference, list candidates with `list_steward_backlog_items` (filter `states: ["queued"]`) and confirm before claiming; if it matches more than one, show the candidates and ask.
- **A steward's top item.** Resolve the steward with `list_stewards` (pass `repository` across multiple workspaces; if none matches, say so and list available stewards rather than guessing). List its queue with `list_steward_backlog_items` (`states: ["queued"]`), take the highest-priority queued item. If the steward's queue is empty, say so and stop; do not fall back to the repo-wide top item unless asked.

### Working the item
1. Inspect repository instructions first: `AGENTS.md`, `CLAUDE.md`, README, package scripts, CI docs.
2. Check for an existing local branch or open PR for a previously claimed item; continue it rather than claiming a second one unless the user asked for a new claim.
3. **Claim** with `manage_backlog_work` (`action: "claim"`). Omit `identifier` for the repo-wide top item; pass the resolved id/reference for a specific item or a steward's top item. Register the branch you will push (prefer the branch returned by a prior `peek`; else `steward/<short-task-slug>`).
4. Read the claim response: capture backlog identifier, steward, repository URL, objective, rationale, and registered branch. Confirm it is the item you intended.
5. `git fetch origin`. Prepare the local workspace on the exact registered branch — prefer `steward backlog setup <backlog-id-or-reference> --base-ref origin/main`; else create the worktree manually from `origin/main` with that exact branch. Confirm clean and correctly based with `git status --short --branch`.
6. **Reconcile (see above): is this already done?** If yes, dismiss with evidence and stop here.
7. **Plan-review with the steward via `consult`, then implement.** Draft a short implementation plan for the claimed item and consult the owning steward against that exact already-claimed item — do not re-select or re-resolve the item, so the consulted and claimed item can never diverge. Fold its guidance in; the steward's planning input is the highest-value part of working its item. Then implement against the reviewed plan, scope tied to the claimed item and its steward lens.
8. Run the repository's required local validation (build, test, lint, typecheck — prefer the local CI-equivalent command when one exists).
9. Commit and push the claim branch.
10. Open a PR targeting `main` with a concise summary and validation results. Verify the PR head branch is the registered claim branch — branch matching is the Steward backlog link.
11. Monitor the PR with the **PR Monitoring Loop** until merge-ready (single-item mode babysits to green; batch mode does not — see below).
12. If `autonomy: merge` and the PR is green, review-clean, and not draft/blocked/conflicted, merge it. Otherwise leave it for the user.
13. On a clean finish, close with the **Closing Stat Line**.

## Direct Run — Batch Session (max-items + scope, or a nightly routine)

A bounded session that makes broad progress, in two phases, then re