# Backlog > Manage approved desired work from intake through refinement, ranking, execution state, cancellation, and archival. Use when creating or changing Epics, Stories, Tasks, or Bugs in docs/backlog. - Skill: `beeltec/backlog` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add beeltec/backlog` - Raw SKILL.md: https://api.skillmd.com/api/skills/beeltec/backlog/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: beeltec (https://skillmd.com/u/beeltec) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/beeltec/backlog --- # Backlog `docs/backlog` owns desired project deltas and execution state; never treat completed backlog work as accepted until the relevant wiki concepts are updated. Use `$wiki` for accepted-knowledge operations; never mutate wiki concepts inside a backlog transaction. Stay on the current branch; never touch `docs/tasks`. ## Authority The project owner controls durable intent and priority. Obtain explicit approval before: creating any record (even a lightweight proposal); changing an outcome, scope, criterion wording, work type, parent, or initial child set; changing relationship links; adding to or reordering global rank; moving work to `ready`; walking work back from `ready` to `proposed`; cancelling work (including its rationale and the disposition of unfinished children); or changing accepted wiki state. Approval covers only the exact transaction presented — never infer it from earlier discussion, a plan, silence, or permission to inspect files. Record approval in `## Execution` when readiness requires it and preserve provenance. Under `$to-product`, its contract approves every schema-valid record/Epic transaction the PRD requires: creation, rewrite, split/merge, type, scope, criteria, exclusions, child set, parentage, relationships, rank, readiness, claims, status, cancellation, recovery, and archival. It never authorizes unrelated or out-of-PRD implementation. An invoked gate-backed workflow authorizing an agent/session for a named standalone item or Epic permits one start transaction, temporary claims, aggregated evidence, normal lifecycle transitions, and one final completion/archive transaction. An Epic may move itself and required children to `in-progress`, claim each child under one session/acceptance branch, then complete/archive atomically. This authority never changes wording, scope, parentage, relationships, priority, cancellation, readiness approval, or accepted wiki state. ## Preflight Before proposing or applying a mutation: 1. Resolve the repository root; read all applicable `AGENTS.md`, `CLAUDE.md`, and nested instructions. 2. Require the `$setup-project` scaffold: `docs/wiki/index.md`, `docs/wiki/maintenance.md`, `docs/backlog/index.md`, `docs/backlog/maintenance.md`, all four backlog type templates, and `scripts/validate-project.mjs`. If any is missing, stop and direct the user to `$setup-project`; do not improvise a partial scaffold. 3. Run `node scripts/validate-project.mjs`; on an invalid baseline, report and stop unless the user explicitly asks to repair that state. 4. Read the wiki root index, maintenance rules, ubiquitous language, nearest relevant indexes, and every relevant accepted-state concept. 5. Read the backlog root index, maintenance rules, relevant type templates, active and archive indexes, all records related by parent or relationship, and every record needed to determine inward links and blocking state. 6. Inspect active and archived IDs before allocation, the complete global rank, the current branch, and staged/unstaged changes. Preserve unrelated work; never stage it. When steps 4–6 expose at least two independent read-only concerns, invoke `$parallel-execution`. Keep synthesis, owner decisions, and every mutation in this context. Steps 4–6 apply to authority-changing transactions. Gate-backed start, recovery, and final acceptance bookkeeping uses steps 1–3, every record in the authorized acceptance unit, and git state. It may aggregate supported evidence and perform only the workflow-authorized claims, lifecycle transitions, required terminal rank removal, and archival; it cannot change scope, priority, relationships, parentage, cancellation, or accepted knowledge. Project-local maintenance rules are authoritative. If they conflict with this skill or cannot represent the transaction, stop and explain rather than weakening validation. ## Intake Keep intake conversational until the owner approves a proposed record and its exact rank placement. Capture provenance (request, issue URL and comment, spec path, conversation date); read any referenced issue, file, or URL completely before drafting. A lightweight proposed record needs only: - **Epic:** next unused immutable `EPIC-NNN`; type `epic`, a concise outcome-centered title, `status: proposed`; a specific problem, delta, or outcome; declared empty or approved relationship arrays, `cancelled_reason: none`, and provenance. - **Executable item:** next unused immutable `WORK-NNN` from the one global sequence shared by Stories, Tasks, and Bugs; the best-supported type, a concise title, `status: proposed`; a specific problem, delta, or outcome; `parent: EPIC-NNN` or `parent: none`, all relationship fields, empty claim fields, and provenance; an explicitly approved position in the one global executable-work rank. Both start at `decisions: pending` unless the significance test has already been applied and recorded. Allocate Epic and work sequences independently by scanning active and archived records; never reuse or renumber an ID. Use the type template as the shape, replace template instructions with known facts, and state unresolved detail plainly in the body — no placeholders in the frontmatter outcome. Add `## Provenance` when the source is not already durably clear. Standalone work is first-class: `parent: none` and `standalone/`; never manufacture a single-item Epic. Before writing files, present the proposed type, ID, title, outcome/delta, provenance, parent, relationships, and exact rank position (plus, for an Epic, any initial child scope) and wait for explicit approval. ## Refinement Refine against the matching installed template and accepted wiki state: - **Story:** a stakeholder-visible behavior delta — who observes what changed behavior; criteria observable from that stakeholder boundary. - **Task:** a bounded engineering or operational result — a concrete project-state delta with verification evidence, not a layer-only activity. - **Bug:** an observed failure against accepted behavior — impact, reproduction conditions, behavior to restore, a cheapest reliable failing-before/passing-after check, and regression evidence; never require a new unit test for the reproduction. Slice work into the smallest independently implementable, verifiable outcome. Prefer vertical behavior or bounded operational results over layer work or agent-sized busywork. Checklist subtasks are coherent implementation steps with scope and one cheapest observable verification; use none when decomposition adds no value. Keep verification minimal and proportional. Plan implementation and real-path smoke proof first; reuse existing coverage. Add a test only for an uncovered observable contract: one acceptance-critical browser E2E for user-visible behavior, integration/contract coverage for a boundary, or unit coverage only for isolated edges or invariants impractical to prove higher. Never prescribe feature TDD, coverage targets, duplicate layers, or excessive E2E. An owner-specified tool binds, but implies no extra depth. For Epics, refine a measurable coordinated outcome, objective criteria, exclusions, useful child scope, and a provisional serial execution graph naming dependencies, shared contracts/files, conflict domains, child order, and required live-code revalidation. Parentless work stays standalone when no genuine shared outcome requires an Epic. Present every proposed scope, criterion, parent, relationship, or rank change for explicit owner approval before editing. ## Definition Of Ready Reject `proposed -> ready` unless the full Definition of Ready in `docs/backlog/maintenance.md` holds — every requirement, including `decisions` resolved off `pending`: `draft` with each qualifying decision drafted under `## Decisions` in ADR shape, naming any ADR it would supersede, or `none` with the significance-test reason. Never allocate an `ADR-NNN` inside a backlog transaction; drafted decisions are published by `$wiki` at post-acceptance reconciliation, and the allocated IDs then replace `draft`. A ready Epic additionally requires an approved outcome, objective acceptance criteria, a coordination approach with the provisional execution graph, and at least one approved child. Show the owner the complete candidate record, rank position, and validation-relevant relationships before requesting the transition; approval to refine is not approval to become ready. ## Relationships And Actionability Use only the schema fields in `docs/backlog/maintenance.md § Relationships`: directional links live on the outward/source record, `relates_to` is added or removed on both records in one transaction, and a child's `parent` plus physical placement represent membership — keep the Epic's scope and indexes consistent with that child set. Reject self-links, missing targets, duplicate links, blocking cycles, and active-to-archived links; never invent reciprocal fields the schema does not define. Actionability is calculated — never a `blocked` status or field. An item is actionable only when its status is `ready` and no nonterminal active record has an outward `blocks` link to it; otherwise report the blocking record IDs. Rank expresses owner priority, not actionability, so blocked work stays ranked until terminal. ## Ranking The ordered links under `## Global executable-work rank` in `docs/backlog/index.md` are authoritative: every active unfinished `WORK-NNN` exactly once; Epics never appear. Any insertion, reorder, or removal other than a required terminal removal is an owner-controlled priority transaction. When proposing intake or reprioritization, show the current order and the exact resulting order or an unambiguous before/after position; apply only the approved order. Remove done or cancelled work from rank in the same transaction as its terminal transition, including a child that remains inside an active Epic directory. ## Execution Claims And Status For a standalone item, verify actionability and claim it in one start transaction. For an Epic, verify every child, move the Epic and required children to `in-progress`, and claim each child for one session/acceptance branch in one start transaction. Epics have no claim fields. Renew before expiry; never overwrite another live claim. Keep focused-check and subtask evidence in the workflow ledger during execution. In the final transaction, check only supported criteria/subtasks, clear claims, set the standalone item or every Epic child and the Epic `done`, remove terminal rank entries, and archive as required. Required accepted-state wiki updates precede this transaction. Incomplete evidence forbids `done`. Release unfinished standalone work or the complete unfinished Epic unit to `ready` and clear owned child claims in one recovery transaction. Never expose a partially accepted Epic. ## Lifecycle Exits When the approved transaction is a `ready -> proposed` walk-back, a cancellation, or an archival, read [references/lifecycle-exits.md](references/lifecycle-exits.md) before proposing it — it owns those procedures, including per-child dispositions and atomic Epic archival. Intake, refinement, readiness, ranking, and claim transactions never read it. ## Durable Transaction For each approved mutation: 1. Restate the exact approved transaction and affected records. For gate-backed bookkeeping, skip the restate — the gate and named work item suffice. 2. Edit all affected records, reciprocal links, indexes, and rank as one logical transaction, with no unrelated cleanup. 3. Run `node scripts/validate-project.mjs`. Fix all errors and review warnings. If it cannot pass, do not commit; report the invalid transaction. 4. Inspect `git diff`, `git diff --cached`, and `git status`; for a bookkeeping transaction, stage first and inspect once with `git status --short` and `git diff --cached`. Stage only the transaction's intended `docs/backlog` paths; handle a separately approved wiki update as its own validated workflow and commit. Never use broad staging commands. 5. Verify the staged path list and diff contain no unrelated files, secrets, working notes, or `docs/tasks` content. 6. Create one concise Conventional Commit, normally `docs(backlog): `. Keep temporary claims in their own transaction when practical. 7. Report the commit hash, changed records, resulting statuses and actionability, rank effects, and validation result; for a bookkeeping transaction, one line — the commit hash and what was checked or changed. End with `Next step:` — one exact command the transaction implies (e.g. a `ready` transition → `$implement WORK-NNN`); omit when none follows. If approval is denied or changed, revise the proposal in conversation without mutating files. If unrelated checkout changes overlap an affected file, preserve them and ask before proceeding when a safe narrow transaction is not possible.