Backlog

Create and manage consistent, machine-readable entries in .context/backlog/ with origin tracking and lifecycle (register · list · close).

Sub-actions

Dispatch

# Bare-word sub-actions route to their own script; everything else is register-item.sh,
# which owns the flag interface. Without this, `/aidex:backlog triage` reached
# register-item.sh and died on "unknown option: triage".
case "${1:-}" in
  triage)   shift; bash "${CLAUDE_SKILL_DIR}/scripts/triage.sh" "$@" ;;
  sweep)    shift; bash "${CLAUDE_SKILL_DIR}/scripts/sweep-kickoff.sh" "$@" ;;
  define)   shift; python3 "${CLAUDE_SKILL_DIR}/scripts/define-check.py" "$@" ;;   # then read § Define run mode
  quick-wins) shift; python3 "${CLAUDE_SKILL_DIR}/scripts/quick-wins.py" "$@" ;;
  detect-resolved) shift; python3 "${CLAUDE_SKILL_DIR}/scripts/detect-resolved.py" "$@" ;;
  worklist) sub="${2:-}"; shift 2
            bash "${CLAUDE_SKILL_DIR}/../conventions/scripts/worklist-${sub}.sh" "$@" ;;
  *)        bash "${CLAUDE_SKILL_DIR}/scripts/register-item.sh" "$@" ;;
esac

When invoked with no arguments, the script prompts interactively. When invoked with arguments, it runs non-interactively and is suitable for programmatic use by other skills.

Autonomy — working / sweeping the backlog

When asked to work several items in a row ("resuelve los backlogs seguidos"), first fix the order once via the AskUserQuestion survey → a durable .context/worklists/ work-list (worklist-new.sh — read ${CLAUDE_PLUGIN_ROOT}/skills/conventions/references/worklist-conventions.md before writing one: it holds the queue format, the gate-policy block, and which of the three classes of mid-run question the queue is meant to absorb), then walk it with worklist-advance.sh instead of pausing between items to ask "what next?" (the dominant un-governed stop). The survey may fold in plan/audit refs too — the work-list is cross-source, not backlog-only.

On each item the walk lands on, run start-item.sh <BL-id> before working it. That is the transition to doing and, for type: bug, the route into RED→GREEN — worklist-advance.sh only names the next item, it does not open it.

When asked to work or sweep the backlog autonomously, resolve every safe + additive item to completion before stopping. Do not halt with "the rest needs your decision": classify each open item first, and for any you would otherwise pause on, decide it yourself against the policy in the ARBITER block in workflow-core.md — weigh the item + the standing autonomy surface + proof the fix is safe. Implement the ones you rule CONTINUE for (commit per item; deps and additive migrations are not gated), and batch the ASK/STOP ones into a single end-of-run list — never stop the sweep on the first item that needs you. When the policy is unclear, fall back to the autonomy canon and proceed. model-policy: per-stage: every subagent this skill launches pins its own model and effort rather than inheriting the run's. This is the gate that turns "I resolved 2, the other 15 need you" into "I resolved the 14 safe ones; here are the 3 that are genuinely yours."

Sweep run mode (/aidex:backlog sweep)

Running a whole batch of XS/S items is a run mode of this skill, not a new skill (ADR decision/2026-08-06-worklist-entry-point-is-backlog). Its policy is references/sweep-execution-policy.md — read it before starting a sweep; the six stages there are the run. In short: one interactive kickoff (an OPEN WORK-LISTS header resolved first, sweep-eligible.py, detect-resolved over the open set, triage verdicts written into the items, worklist-new.sh --mode sweep, one consultation artifact), then headless; per item start-item → proof rows → close-item --sweep, which refuses without them; the checkpoint every ~5 items or at any cluster boundary is checkpoint-conventions.md, not restated here — its handoff seed additionally carries the work-list path, the item just closed, what ran with which exit codes, and what is ungated; sweep-gate.sh --worklist <the work-list path> once at the boundary; sweep-report.sh, the Route S page (opened before worklist-close.sh when it asks anything, after it when it asks nothing) at close-out, branch left ready, merge asked. Size is the wrong gate: the entry gate is Acceptance — an item with no acceptance criteria is not small, it is undefined.

Define run mode (/aidex:backlog define)

A sweep chooses among defined items; it does not define them. Contract and run: references/03-define-run-mode.md — read it first.

Entry format

Each entry is a single dated file: .context/backlog/YYYY-MM-DD-bl-nnn-<slug>.md, written by register-item.sh — front-matter followed by a Context / Acceptance / Notes body.

Never choose the BL-NNN yourself — always register through the script. Reading the index for the highest id and adding one is the same race the script exists to prevent, with a much wider window: the script's scan-to-write gap is microseconds, a human or an agent doing it by hand leaves minutes, and ids have been minted twice that way. register-item.sh claims the number atomically against a repo-global ledger; nothing outside it can. --check-ids remains the detector for ids that got in some other way, but detection after both files exist is not the same as prevention.

Write the entry in English (canon §Language, D-04) — even when the conversation is in another language. The description/title and body are both English; only communications/ bodies keep their native language. This governs the ENTRY, not the kickoff consultation, which is addressed to the reader and follows the profile's language: (BL-371). register-item.sh's Context placeholder repeats this at the point of writing, and bash scripts/normalize-language.sh reports items that drifted.

The complete front-matter schema is the single-source 15-field table in references/01-backlog-conventions.md (id and commits are machine-required — the lifecycle breaks without them; surface and verify say how the item will be proven, and a sweep cannot close it otherwise). Don't re-copy the schema here; author entries via the script or straight from that table.

Lifecycle

open ⇄ _deferred (blocked) → doing → done / dropped

1. open — entry created, not yet scheduled
2. _deferred (blocked) — open but cannot start: an external blocker exists. The item is moved to backlog/_deferred/, status stays open, and blocked_by MUST be populated. It is not in the active queue and is not _archive/ (archive is terminal). Use defer to park it and reactivate to bring it back.
3. doing — active work, opened with start-item.sh rather than by editing status by hand. That script is also the bug route: an item with type: bug prints the RED→GREEN procedure on start, so bug work enters the regression-test-first cycle from the backlog lifecycle instead of depending on a bug-report phrasing that tracked work never uses. A plan may exist in .context/plans/ (link in Notes). If the item's acceptance criterion is machine-checkable (a gate the work should iterate against), it may instead link an loop loop-spec in .context/loops/. Default stays a plan.
4. done — shipped; archived to _archive/ on close (D-10), not after a delay
5. dropped — won't do; reason in Notes; archived on close

Deferring is reversible (open ⇄ _deferred/); closing is terminal (→ _archive/).

• Defer/reactivate moves the file between the active root and backlog/_deferred/, sets/clears blocked_by, stamps updated, and rebuilds the index. The 00-index.md lists deferred items under ## Deferred. Use the defer / reactivate sub-actions rather than moving files or editing blocked_by by hand.
• Closing an item is an atomic operation (status → record commit → move to _archive/ → rebuild index). Use the close sub-action rather than editing status by hand. The 00-index.md keeps a one-liner per closed item under ## Closed; full bodies live in _archive/.

Commit provenance (D-09) and audit escalation

Commits live where the work happened — in the item when fixed directly, in the plan when escalated, never both; captured by the Backlog: BL-NNN / Plan: <slug>#<phase> trailer via install-commit-hook.sh, or close-item.sh --commit <sha> by hand. An audit finding arrives with origin: audit and origin_ref: audit/<run>/<finding-id>. Details: references/04-commit-provenance-and-audit-escalation.md.

Self-check

Validate the artifact you just wrote and fix any violation before closing:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/conventions/scripts/validate.py --type backlog

With a ratchet baseline (.context/.validate-baseline.json), non-zero means a NEW violation — fix it before closing.

Related

• audit — uses this skill for escalation (/aidex:audit escalate)
• conventions — parent convention for .context/backlog/
• artifact — renders the backlog as an interactive HTML board on demand (render.sh backlog); publishing stays user-gated

triage, quick-wins and detect-resolved answer three different questions

Is the backlog healthy? (triage — health, not prioritization) · What first? (quick-wins) · Is any of this already done? (detect-resolved). Details and fan-out: references/02-triage-quick-wins-detect-resolved.md. One rule survives the split: detect-resolved never closes an item — closing is a separate, deliberate act with the evidence attached.