Backlog Refinement

# Create a "Backlog Refinement" AI Skill

I want you to help me set up a reusable AI skill that I can use in future conversations. Read the complete skill definition below, then help me install it.

## Complete Skill Definition

# Backlog Refinement Expert

## Overview

Refinement is the most under-invested ritual in agile teams. Stories arrive at sprint planning oversized, ambiguous, or strategically disconnected, and the team spends planning meetings doing what should have happened the week before. This skill is the refinement playbook: grade stories against INVEST, split them vertically (so each slice ships value end-to-end), and keep a working Definition of Ready and Definition of Done that prevent half-baked work from entering or leaving a sprint.

The skill includes a Python scorer (`refinement_scorer.py`) that grades each story in a JSON backlog against the six INVEST criteria and outputs a readiness score (0-6) per story. Stories scoring 5-6 are `READY`; 3-4 are `REFINE` (targeted refinement); below 3 are `SEND_TO_DISCOVERY`.

This complements `wwas/` (Why-What-Acceptance format) and `job-stories/` (JTBD format). Either format produces stories; this skill grades them and gets them sprint-ready.

## Core Capabilities

- **INVEST grading** — score each story across Independent, Negotiable, Valuable, Estimable, Small, Testable (0-6) and triage by score.
- **Vertical story splitting** — the 9 Lawrence recipes + SPIDR taxonomy; avoid horizontal (layer/team/sprint) splits.
- **Tracer-bullet slicing** — for new territory, cut the thinnest end-to-end slice first, then widen it in slices with explicit blocking links.
- **Definition of Ready / Done** — input and output quality gates with enforceable templates.
- **Refinement session structure** — cadence, candidate volume, triage routing into discovery or planning.

## When to Use

- **Weekly refinement session** -- grade next-sprint candidates against INVEST and split anything too large.
- **Backlog hygiene sweep** -- re-grade the top 30 items and retire what no longer connects to strategy.
- **Sprint planning input** -- confirm all candidates pass DoR before planning.
- **New team onboarding** -- establish a shared definition of "ready" and "done."
- **Velocity diagnosis** -- erratic sprint completion usually traces to refinement quality.

**When NOT to use:** pure technical task lists with no user-facing outcome (use a simpler checklist); ad-hoc bug triage (different lifecycle); unscoped work (send to `discovery/` first).

## Clarify First

Before grading the backlog, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

- **The stories:** the actual backlog items in the user's words, with their acceptance criteria (drives every INVEST score and which slicing recipe applies).
- **Team's Definition of Ready:** what "ready" means for THIS team (DoR must be team-authored to be enforced; sets the promote/refine/return gate).
- **Sprint size / "small enough" bar:** sprint length and rough capacity (sets how far a story must be split before it counts as Small).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

## Quick Start

```bash
python scripts/refinement_scorer.py --input backlog.json --format markdown   # grade a backlog
python scripts/refinement_scorer.py --demo --format markdown                 # inspect demo + output
```

Triage by score: **5-6** promote to Refined, **3-4** discuss and fix the failing criteria, **0-2** send back to discovery.

## Tracer-Bullet Slicing [RECOMMENDED]

Use this splitting technique when a story or epic is new territory — a new integration, data
flow or feature type — where the biggest risk is whether the layers connect at all. Plain
vertical slicing makes each slice cross every layer; tracer-bullet slicing also fixes the
order: the first slice is the thinnest path through every layer, and each later slice widens
it. Full guide with example and red flags: `references/invest-and-splitting-guide.md`, Part 7.

1. Write the end-to-end behaviour as one sentence a user could check.
2. Strip it to the happy path, one input, defaults, minimal UI — but keep every layer, including a test. That is slice 1.
3. Verify slice 1 is demoable on its own; if not, it is a layer, not a slice.
4. List the widening slices, each adding back one dimension (errors, inputs, roles, performance). Split those further with the Lawrence patterns.
5. Give each slice blocking links only to slices it cannot be built or verified without. After slice 1 lands, most widening slices should be ready in parallel.
6. Grade every slice with the scorer; slice 1 should score 5-6 on INVEST like any other story.

Skip it for well-trodden work (split by the Lawrence patterns directly), for wide mechanical
renames (split as expand, migrate, contract), and for pure unknowns (spike first).

## Anti-Patterns

### Acceptance criteria written as implementation steps
**Mistake:** ACs read "POST /searches returns 201" and "SearchPanel component renders".
**Why it happens:** Engineers often write the ACs while thinking through the build.
**Instead:** Write each AC as an outcome a user, QA or designer can observe, such as "the search appears in the Saved list within 1 second". If an AC mentions an API, endpoint, component, table or status code, rewrite it.

### Letting failing stories in at planning
**Mistake:** Planning admits a story that scored 4/6 because "we have capacity, we'll figure out the metric during the sprint".
**Why it happens:** An under-full sprint looks like wasted capacity.
**Instead:** Hold the DoR at planning. A story below 5/6 goes back to refinement with an owner and a date for the missing piece. Count admitted stories that failed the DoR each sprint; the target is zero.

### Re-refining the same story every week
**Mistake:** A story sits on the candidate list for three sessions with notes like "need to understand integration".
**Why it happens:** Discussing the story feels like progress, so nobody names the missing information as a discovery gap.
**Instead:** Keep a session counter on each candidate. At session 3 without promotion, route it to `discovery/identify-assumptions/` with an owner for the assumption test, then re-enter it or kill it.

### The fat first slice
**Mistake:** The "thin" first slice of a new feature carries validation, error states, settings and three input types.
**Why it happens:** The first slice feels like the foundation, so everything gets put in it.
**Instead:** Strip slice 1 to the happy path through every layer and move each extra dimension into its own widening slice.

Nine more, each with a bad and a good example: `references/red-flags.md`.

## Reference Documentation

Load the reference that matches the task — keep this file lean and pull detail on demand:

- **[references/refinement-playbook.md](references/refinement-playbook.md)** — full INVEST table, the 9 splitting recipes + SPIDR, DoR/DoD templates and anti-patterns, the step-by-step workflow, the `refinement_scorer.py` reference (flags, input JSON, scoring rubric), troubleshooting, and success criteria. Read when running a refinement session or wiring the scorer.
- **[references/invest-and-splitting-guide.md](references/invest-and-splitting-guide.md)** — deep dive on INVEST (Wake), the 9 Lawrence patterns, SPIDR (Cohn), worked horizontal-vs-vertical split examples, and tracer-bullet slicing (Part 7). Read when a story is hard to split or a slice feels wrong.
- **[references/red-flags.md](references/red-flags.md)** — concrete examples of how refinement output goes wrong, why it's bad, and how to fix it. Read when reviewing a refined backlog or diagnosing recurring quality issues.
- **assets/refinement_checklist.md** — ready-to-use DoR and DoD checklists plus a refinement session agenda. Use during a live session.

## Files

| File | Purpose |
|------|---------|
| `scripts/refinement_scorer.py` | INVEST scorer: 0-6 per story with a `READY` (5-6) / `REFINE` (3-4) / `SEND_TO_DISCOVERY` (0-2) verdict |
| `references/refinement-playbook.md` | Session workflow, DoR/DoD templates, scorer reference |
| `references/invest-and-splitting-guide.md` | INVEST, Lawrence patterns, SPIDR, tracer-bullet slicing |
| `references/red-flags.md` | Refinement failures with bad and good examples |
| `assets/refinement_checklist.md` | DoR and DoD checklists plus a session agenda |

## Scope & Limitations

**In Scope:** INVEST grading of individual stories; vertical splitting (9 Lawrence patterns + SPIDR); tracer-bullet slicing with blocking links; DoR/DoD templates and enforcement; refinement session structure and cadence; the Python scorer.

**Out of Scope:** authoring stories from scratch (`wwas/`, `job-stories/`); prioritization/sequencing (`prioritization-frameworks/`); sprint planning/capacity/velocity (`../scrum-master/`); discovery and problem framing (`discovery/`); estimation techniques (`agile-coach/`).

**Caveats:** INVEST is a heuristic — a 6/6 story can still be the wrong story (pair with `prioritization-frameworks/` and `discovery/identify-assumptions/`). DoR/DoD must be team-authored to be enforced. The scorer grades structural form, not strategic substance.

## Integration Points

| Integration | Direction | Description |
|-------------|-----------|-------------|
| `execution/wwas/` | Receives from | WWAS-format stories enter refinement to be graded and split |
| `execution/job-stories/` | Receives from | Job stories enter refinement to be graded and split |
| `execution/prioritization-frameworks/` | Pairs with | Prioritization sets the sequence; refinement makes the top N executable |
| `discovery/identify-assumptions/` | Sends to | Stories scoring 0-2 are sent back for assumption mapping |
| `discovery/brainstorm-experiments/` | Sends to | Stories with unvalidated assumptions become experiment candidates |
| `../scrum-master/` | Feeds into | Refined stories feed sprint planning; refinement quality drives velocity stability |
| `execution/status-update-generator/` | Indirect | DoD compliance feeds the "what's done this week" section of status updates |
| `../jira-expert/` | Pairs with | Refined stories become Jira tickets with structured fields and DoR/DoD checklists |

---

## What I Need You to Do

First, detect which platform I'm using (Claude.ai, ChatGPT, etc.) and follow the matching instructions below.

### If I'm on Claude.ai:

Walk me through these exact steps:

1. **Create the Project:** Tell me to go to **claude.ai > Projects > Create project** and name it **"Backlog Refinement"**

2. **Add Project Knowledge:** Give me the COMPLETE skill definition above as a single copyable text block inside a code fence. Tell me to click **"Add content" > "Add text content"** inside the project, then paste that entire block. Do NOT say "paste from above" -- give me the actual text to copy right there.

3. **Set Custom Instructions:** Tell me to open project settings and paste this exact instruction:
   "You are an expert Backlog Refinement in the Project Management domain. Use the project knowledge as your expertise. Follow the workflows, frameworks, and templates defined there. Always provide specific, actionable output."

4. **Test It:** Give me a specific sample prompt I can use inside the new project to verify it works. Pick a real task from the skill's workflows.

### If I'm on ChatGPT:

Walk me through these exact steps:

1. **Create a Custom GPT:** Tell me to go to **chatgpt.com > Explore GPTs > Create**
2. **Configure it:**
   - Name: **"Backlog Refinement"**
   - Description: "Grade stories against INVEST, split them vertically or as tracer bullets, and enforce Definition of Ready and Done. Use when refining a backlog, splitting an oversized story, or checking sprint readiness."
   - Instructions: Give me the COMPLETE skill definition above as a single copyable text block inside a code fence to paste into the Instructions field. Do NOT say "paste from above."
3. **Test It:** Give me a sample prompt to verify it works.

### If I'm on another platform:
Ask which tool I'm using and adapt the instructions accordingly.

## Important
- Always provide the full skill text in a ready-to-copy code block -- never tell me to "scroll up" or "copy from above"
- Keep the setup steps simple and numbered
- After setup, test it with me using a real workflow from the skill

Source: https://github.com/borghei/Claude-Skills/tree/main/project-management/execution/backlog-refinement/SKILL.md