# Refine Backlog > Refine a BACKLOG item or not-started STORY by running the SOP §6 Definition of Ready checklist. Use when the user asks to refine the backlog, refine an item, promote to ready, run DoR, gate a story, or invokes /tandem:refine-backlog. Operates as PM hat. Either flips status to ready (if all DoR items pass) OR stops, lists gaps, and asks — never silently promotes. - Skill: `data-ai-xyz/refine-backlog` (Agent Skill) - Install (CLI): `npx skillmds@latest add data-ai-xyz/refine-backlog` - Raw SKILL.md: https://api.skillmd.com/api/skills/data-ai-xyz/refine-backlog/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: DATA-AI-XYZ (https://skillmd.com/u/data-ai-xyz) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/data-ai-xyz/refine-backlog --- # Tandem: refine-backlog (PM hat) Operate as **PM hat**. The user wants to take a BACKLOG entry or a `not-started` STORY through the Definition of Ready gate — either promoting it to `ready` (eligible to pull into work) or surfacing exactly what's missing. This skill is the slash-command wrapper for the kit's canonical refinement prompt. The prompt is the source of truth; this file is the entry point. ## Source of truth @_00-Project-Management/92-Prompts/05-refine-backlog-to-ready.md Follow that prompt verbatim. The sections below add only the slash-command-specific glue + the DoR enforcement contract — do not re-declare the prompt's content here. ## Definition of Ready (DoR) — what we're gating against Per SOP §6, a story is `ready` only when **all** of the following are true. The skill walks each item; missing items abort the promotion with a clear gap list. - [ ] **Linked to a Feature → Epic → OKR or PRD.** Story frontmatter `feature:` and `epic:` set; parent Epic has `okr:` or `prd_section:` populated. - [ ] **AC written as testable checkboxes.** Each AC verifiable by a machine, not by vibes. - [ ] **Paired TESTPLAN exists at the mirrored path.** `33-Testplans/EPIC-NN/FEAT-NN.M/TESTPLAN-NN.M.PP-.md`. - [ ] **Every AC maps to ≥1 TC in the TESTPLAN.** Coverage matrix complete. - [ ] **Every TC has a runnable `Command:`.** No "have a human verify" steps. - [ ] **Dependencies listed and either done or scheduled.** No floating "depends on TBD". - [ ] **Estimate set** (XS / S / M / L). `XL` means split before promoting. - [ ] **`type_of_work` set to a concrete discipline** (`frontend` / `backend` / `infra` / `data` / `docs`) — not the template placeholder. A missing or placeholder value is a DoR gap (it fuels `execution-strategist` sub-agent assignment; see SOP §11.3 / FEAT-03.1). - [ ] **Risks section non-empty.** "None — reviewed YYYY-MM-DD" counts; blank does not. - [ ] **Premise verified.** Any claim the item makes about **another artefact's state** (status / existence / supersession), or any intent to **retire / archive / delete / supersede / mutate** a named `STORY-`/`FEAT-`/`EPIC-`/`ADR-`/`BACKLOG-` artefact, has been **checked against that artefact's current frontmatter**. A claim that contradicts reality — or names an artefact that can't be resolved — is a DoR gap. ## DoR enforcement contract (MANDATORY) This skill **never silently promotes**. The contract: 1. Walk the DoR checklist verbatim — every item gets PASS / FAIL with a one-line reason. 2. If **all** items pass → before flipping `status: not-started` → `ready`, run the **usage-estimate producer step** below, then perform a fill-if-missing check: if the story's `outcome:` frontmatter is empty or absent, apply the `write-outcomes` rules inline — using the story's **title + acceptance criteria + technical notes** (the same input the other four FEAT-14.3 producers use, per ADR-0059's contract) — to generate exactly one plain-text line, then write that line into `outcome:` (fill-if-missing only — never overwrite an existing outcome). Dispatch a sub-agent only under ADR-0105 — write-outcomes runs inline first, rather than dispatching a sub-agent per artefact's named conditions (this producer's own context is near its limit, or an isolation-worthy batch run). Then flip the story (or BACKLOG entry, after conversion) `status: not-started` → `ready`. Atomic edit. Do **not** set `started_at` (that happens at `in-progress`, not `ready`). Show the user the result table. 3. If **any** item fails → **stop**. Do **not** flip status. Show the gap list and the smallest fix for each. Ask the user before patching — the skill never auto-completes the missing pieces (e.g. don't invent ACs, don't fabricate TCs, don't guess at risks). 4. **Sunset check** — per SOP §15, if a story has been `not-started` > 90 days, propose `wontfix` or `archived` instead of refinement. Stale items rot; the kit prefers honest sunsetting over false hope. ### Usage-estimate producer step (MANDATORY at the DoR pass) Every story this skill promotes to `ready` leaves carrying a `usage_estimate:` — the field has existed since STORY-21.2.02 and **nothing ever wrote one**, so every estimate-vs-actual surface in the kit prints an honest null (BACKLOG-0157). Run, per story, before the flip: ```bash node _00-Project-Management/93-Scripts/usage-estimate.js --story ``` - **Fill-if-missing, never overwrite.** A populated estimate is preserved verbatim and the file is left byte-identical, so the step is safe to re-run and safe over a hand-estimated story. - It writes the number **and** a one-line basis into the story's `## Technical notes`. Do not hand-write either — the basis is what makes a variance interpretable later. - If it reports no number because `estimate:` is missing or `XL`, that is a **DoR gap**: report it in the gap list and do not promote. An XL story is split first (SOP §6). - Report the figure in the summary table's Notes column. **The derivation itself is written in exactly one place — do not restate it here or in any skill:** [`_00-Project-Management/90-Standards/USAGE-ESTIMATE-HEURISTIC.md`](../../_00-Project-Management/90-Standards/USAGE-ESTIMATE-HEURISTIC.md). Read it before overriding a produced number by hand; in particular it records why a ledger row is **not** what a chat cost, and why every `type_of_work` multiplier is 1.00 today. ### Premise resolution (the "Premise verified" DoR item) A story can be perfectly well-*formed* and still be *wrong*, because the other DoR items only check structure — never whether the item's stated premise is **true**. To walk the **Premise verified** item: 1. Scan the item's body/ACs for the tell — a phrase shape that makes a **state claim about a named other artefact** or proposes to **mutate** one: *"X is never-started / not-started / superseded / done / blocked / obsolete / duplicate"* or *"retire / archive / delete / supersede / close X"*, where **X is a `STORY-`/`FEAT-`/`EPIC-`/`ADR-`/`BACKLOG-` id**. (Only ids named **with a status claim or mutation intent** — a bare reference in prose does not trip the gate.) 2. **Resolve each named id** and read its current `status:` (and existence). If the artefact can't be found, or its real status contradicts the claim → **DoR FAILS**: do not promote; name the specific mismatch (claimed-vs-actual) and stop, consistent with the "never silently promote" rule above. **Worked example (the regression fixture this guards) — STORY-15.1.02:** it asserted "STORY-04.6.01–05 are five never-started, superseded stories" and proposed to flip them to `archived` — but all five are genuinely `status: done`. Executing it would have silently corrupted the board (done-count 154→149) while **every structural gate stayed green** (`archived` + `completed_at` is enum-legal; R21 doesn't fire on terminal status). The premise check resolves `STORY-04.6.01…05`, sees `done`, and fails the gate before promotion — catching systematically what was previously caught only by luck (execution happening to inspect the targets first). The gap-list path is the skill's load-bearing differentiator vs the plain paste-prompt. Silent or partial promotion would corrupt the kit's "Ready means Ready" invariant — every downstream skill (`execute-story` especially) relies on it. ## Inputs needed - Either: - A path to a BACKLOG entry (`_00-Project-Management/11-Backlog/BACKLOG-NNNN-.md`) — large items get refined into a Feature spec first; small ones promote directly to a Story+Testplan pair. - A path to an existing `not-started` Story (`_00-Project-Management/32-Stories/EPIC-NN/FEAT-NN.M/STORY-NN.M.PP-.md`) — direct DoR gate. - A short list of candidates ("top 5 by priority") if the user wants a batch review. - If the user didn't supply anything, ask: "Which item(s)? Paste a path, a list of paths, or 'pick from not-started' if you want me to choose." ## Load into context Use `Read` / `Glob` to detect existence. Treat missing files as "not present" rather than throwing. - **Target item(s)** at the resolved path(s). - **SOP** — `_00-Project-Management/90-Standards/SOP.md` (specifically §6 DoR + §15 sunset rule). The DoR list above is sourced from §6; if §6 has drifted from this skill's list, **§6 wins** — flag the drift to the user. - **Project context** — `_00-Project-Management/90-Standards/PROJECT-CONTEXT.md` (for stack-specific runnable-command conventions when checking testplan TCs). - **MONITOR** — `_00-Project-Management/42-Monitor/MONITOR.md` for current WIP. After processing, the skill suggests "WIP is currently N in-progress + M in-review. You have capacity to pull K more." - **Parent artefacts** — for each target Story, also load its parent Feature + Epic to verify the strategic-linkage DoR item. - **Templates** — `_00-Project-Management/91-Templates/STORY.template.md` + `_00-Project-Management/91-Templates/TESTPLAN.template.md` (for the gap-fix proposals when ACs / testplans are incomplete). - **Project root `CLAUDE.md`** — for project-specific overrides. ## Task 1. Read each target item end-to-end. 2. Walk the DoR checklist verbatim. Per item: PASS or FAIL, with a one-line reason citing what was checked. 3. If the item is a BACKLOG entry (not a Story yet), additionally judge: - **Story-sized?** Single coherent unit of work, fits an XS/S/M/L estimate → promote by creating STORY+TESTPLAN via `/tandem:split-into-stories` (after refinement). Don't write them inside this skill. - **Feature-sized?** Multi-story scope → suggest the user run `/tandem:split-into-features` on the parent Epic, or draft a new Feature directly. - **Sunset candidate?** Captured >90 days ago, no movement → propose `wontfix` or `archived`. 4. If all DoR items PASS for a Story → flip `status: not-started` → `ready`. Atomic edit. Do **not** set `started_at`. 5. If any FAIL → **stop**. Show the gap list + smallest fix per gap. Ask the user before any patching action. 6. Repeat per item. Process **serially** — one item at a time, user reviews each pass/fail decision before moving on. 7. Emit the summary table at the end (see Output rules). ## Output rules - **Never silently promote.** Every gap blocks the flip. No "I'll just fill that in for you" — the user owns the decision to patch or defer. - Process candidates **serially**, not in parallel — gives the user a beat to review each pass/fail call. - Show a summary table at the end: | Item | DoR result | Notes | |---|---|---| | STORY-NN.M.PP | ✓ ready | Promoted 2026-MM-DD | | STORY-NN.M.PP | ✗ fail | Missing: estimate, risks. Smallest fix: ... | | BACKLOG-NNNN | ✗ sunset | Captured 2025-MM-DD (>90 days), no movement — propose wontfix | - Do **not** pull anything to `in-progress` here. That's `/tandem:execute-story`. - After processing, surface capacity guidance: "WIP is currently N in-progress (max 2) + M in-review (max 3). You have capacity to pull K more. Top Ready candidate: STORY-NN.M.PP." ## Non-negotiable rules from CLAUDE.md - Frontmatter timestamps — flipping to `ready` touches `status:` only. **Do not** modify `started_at` or `completed_at`. - Status enum — `ready` is one of the closed 9 values; do not invent intermediate states. - DoR gate is **MANDATORY** — no shortcuts, no partial credit, no honour-system bypass. - Sunset rule (SOP §15) — items `not-started` > 90 days should be honestly retired rather than perpetually refined. ## End-of-session summary (always emit) - Items processed: N (serial) - Promoted to `ready`: list of paths - Blocked on DoR gaps: list of paths + gap-count per item - Sunset proposed: list of paths - WIP after this session: + (capacity for K more) - Top Ready candidate to pull next: STORY-NN.M.PP ## Next command Next: `/tandem:execution-strategist` `/tandem:split-into-stories ` — if a refined item turned out to be feature-sized. Or, if a Story is now `ready` and within WIP capacity: `/tandem:execute-story ` — start the work.