---
name: backlog-refinement
description: Identify backlog stories that need refinement by querying `imdone ls -q list=TODO -f json`, inspecting local story files and attachments, and drafting the smallest HDD-style refinement needed to make a story execution-ready. Use when developers or product owners want to find unrefined TODO stories, rank refinement candidates, or refine a selected story before implementation.
---

# Backlog Refinement

Find the TODO stories that are least ready for implementation, recommend the best candidate to refine now, and then do the minimum outcome-first refinement work needed to make that story executable for developers and product owners.

## Sweep The Backlog

Start with:

```bash
imdone ls -q list=TODO -f json
```

Treat the JSON output as the candidate set. Each item usually includes:
- `title`
- `filename`
- `meta.jira[0]`
- `meta.issueType[0]`
- `meta.status[0]`
- `meta.jiraUpdated[0]`

Filter the candidate set before reading files:
- keep only items where `meta.issueType[0]` is `Story`
- ignore `Task`, `Epic`, and other issue types unless the user explicitly asks for them
- prefer stories under `current-sprint/`
- if `filename` starts with `backlog/` but the current working directory is already `backlog/`, strip the leading `backlog/` before opening the file

If the user names a story key, still run the sweep first so the recommendation is grounded in current TODO stories, then focus on the requested story.

## Detect Refinement Gaps

For each retained story, read:
- the issue markdown file from `filename`
- `attachments/success-metrics.md`

If an attachment is missing, empty, placeholder-only, or still stock-template content, treat it as missing refinement.

Use these fallback templates when needed:
- `.imdone/templates/stock/hypothesis-driven-development.md`
- `.imdone/templates/stock/partials/success_metrics.md`

A story needs refinement when one or more of these are true:
- the story does not describe a clear user or stakeholder outcome
- acceptance criteria are missing, vague, or not binary/testable
- the story jumps directly to implementation tasks without a clear slice, hypothesis, or success signal
- HDD attachments are missing or placeholder-only
- design or plan artifacts do not identify the first boundary to touch or the thinnest execution path
- the scope is obviously larger than a thin slice that could be delivered in about three days
- the story reads like an investigation or bundle of tasks instead of a single outcome-focused change

## Rank Candidates

After inspecting candidates, produce a short ranked list with:
- issue key and title
- why the story is not ready
- the smallest refinement move that would make it materially more executable

Rank using these heuristics in order:
1. story has the biggest readiness gap but enough context to refine now
2. story is outcome-relevant and still shaped like a story, not a pure task bucket
3. story is missing HDD artifacts or has obviously weak acceptance criteria
4. story looks small enough to rescue with one refinement pass
5. break ties by the most recently updated story

Recommend one story to refine now unless the user already chose one.

## Refine The Selected Story

Once a story is selected, use the HDD pattern, but only write the smallest artifacts needed to unblock implementation.

Read the story and attachments first. Extract:
- who benefits from the change
- what observable behavior must change
- what constraints must stay unchanged
- what unknown would kill the story if false
- how success will be verified

Work in this order:
1. Vertical Slice
2. Hypothesis
3. Success Metrics
4. Validate Assumptions

Stop refinement there. Do not draft or write `Demo`, `Design`, or `Plan` during backlog refinement.

Do not force every section if the story only needs a smaller repair. Write only what closes the specific refinement gaps you found.

## Writing Rules

- Draft, then confirm, then write.
- Once the user approves a draft, write it to the actual story file or attachment immediately before moving to the next artifact.
- Prefer letting the user react to the file-backed version of the content instead of keeping approved text only in chat.
- Ask more critical questions, not just alignment questions. Push on ambiguity, hidden scope, weak ownership, unverifiable outcomes, and missing reviewer input before locking content in.
- When presenting multiple-choice options, always number them explicitly (`1.`, `2.`, `3.`) so the user can reply with the number alone.
- When reviewing content with a human, explicitly ask whether the relevant reviewers are in the room before locking it in.
- For vertical slice and acceptance criteria, ask whether UX is in the room when the story has user-facing behavior, workflow, copy, or presentation implications.
- For hypothesis, success metrics, and assumptions, ask whether engineering is in the room when technical feasibility, system boundaries, integration risk, or verification approach materially shape the story.
- Keep everything thin and local.
- Prefer concrete language over process language.
- Rewrite acceptance criteria into explicit precondition, action, and observable result when needed.
- Preserve user wording when it is already good enough.
- If a story cannot be made binary and thin, narrow the slice instead of drafting downstream implementation artifacts.
- Do not create or edit `attachments/demo.md`, `attachments/design.md`, or `attachments/plan.md` as part of this skill.
- If you create missing HDD attachments, create only the files needed for the current refinement pass.

Write locations:
- vertical slice, hypothesis, and key assumption: inline in the story when that structure exists
- success metrics: `attachments/success-metrics.md`
- definition of done notes only if needed to remove ambiguity: `attachments/dod.md`

## Interaction Pattern

When identifying candidates, present results in this shape:

```text
Top refinement candidates:
1. MCADS-XXXX - Title
   Why it needs refinement: ...
   Smallest next refinement move: ...
2. ...

Recommended now: MCADS-XXXX because ...
```

When drafting refinement content, present one artifact at a time in this shape:

> *[short framing line]*
>
> Based on the story, here is a draft:
> **"[draft]"**
>
> Does this look right? Edit it, say yes to accept, or replace it entirely.

Before writing an accepted draft, ask the relevant review-presence question when appropriate:
- Vertical Slice / acceptance criteria with user-facing implications: `Is UX in the room for this review?`
- Hypothesis / Success Metrics / Validate Assumptions with meaningful technical risk or implementation coupling: `Is engineering in the room for this review?`

Also ask at least one critical question when the draft could hide a real execution risk, such as:
- `What would make this slice fail even if the code is implemented exactly as written?`
- `What dependency, stakeholder decision, or external data contract is still assumed here?`
- `What would a reviewer point to to say this is done, and is that evidence binary?`
- `Is this still one outcome-focused change, or have we bundled multiple tasks into one story?`
- `What is the smallest thing we could ship or prove first if this turns out to be larger than it looks?`

If the relevant reviewer is not present:
- call out that absence as added design or delivery risk
- tighten the draft so any unconfirmed assumption is explicit
- avoid overstating confidence in user impact, feasibility, or verification

If the user confirms, write the artifact to file immediately instead of batching several accepted items.

## Minimal Reference Loading

Load only the reference file needed for the current decision:
- `references/vertical-slicing-experts.md` for vertical slice and acceptance criteria
- `references/product-builder-experts.md` for hypothesis, risk, and success metrics
- `references/lean-architecture-experts.md` for design and plan framing

Use one short framing line or one to two alignment questions from the relevant file when the story is fuzzy. Do not turn the session into a lecture.

## Notes

- Re-run the TODO sweep whenever the user asks for the current best refinement candidate.
- Prefer updating the story artifacts over writing free-floating advice.
- If no story is a good refinement candidate, say that directly and explain whether the blocker is missing domain context, missing stakeholder input, or story scope that is still too broad.
