Skip to content

tibursocampos/agent-dev-toolkit / core/skills/refine-story

refine-story

Verified

Refine a Bug, User Story, or Technical Story into structured markdown with BDD acceptance and a quality scorecard. Use when refining backlog or invoking /refine-story.

---
name: refine-story
description: Refine a Bug, User Story, or Technical Story into structured markdown with BDD acceptance and a quality scorecard. Use when refining backlog or invoking /refine-story.
---

## STOP - Read before ANY tool call

Read `_shared/skill-boilerplate.md` first. It holds the guardrails read, the session gate rule, the user `sim` rule, the one-step rule, the gate check, and the user chat language rule. The steps below are skill-specific only.
---

# Skill: refine-story

## Trigger
**Negative signal:** applies as defined in `_shared/skill-boilerplate.md`; the skill-specific signals are listed below.


Invoke when the user asks for: `/refine-story`, `refine backlog item`, or quick intake before SDD / Orchestrated Delivery.

Optional: path to existing notes, pasted description, or explicit mode (`feature` | `tech` | `split`).

**Refine mode (mandatory — no silent default):**

| Mode | Explicit invoke examples | Default item types |
|------|--------------------------|--------------------|
| **feature** | `feature`, `modo feature`, `1` | User Story or Bug |
| **tech** | `tech`, `technical`, `modo tech`, `2` | Technical Story |
| **split** | `split`, `modo split`, `3` | Any type — split-ready steps + checklist handoff |

If the invocation does **not** name a mode: **STOP** after gate check (-1) / before deep refine and ask once, in the **user chat language**, then wait. Do **not** assume `feature`. Do **not** load any mode playbook until answered.

That question applies only to **direct** invocation. When `invocation_context=orchestrated`, the parent passes `mode=feature` or `mode=tech`. Do not ask the mode. Load that playbook. For `mode=feature`, also load `references/feature-research.md` (`references/feature.md`).

Question component form (ids fixed in English; labels rendered in the user chat language):

```text
header: refine-story mode
question: refine-story mode?
single select:
- feature: User Story or Bug framing
- tech: Technical Story framing
- split: steps ready for /split-story-checklist
```

Render the question and the three labels in the user chat language. Keep the mode ids `feature`, `tech`, and `split` in English. The descriptions above give the meaning of each id; they are not labels to copy.

## Outcome

Structured **markdown** in chat (BDD acceptance criteria + implementation steps) and a **quality scorecard** aligned to portable backlog refinement patterns.

**Persistence (prefer in order):**

1. `features/NNN-slug/USnn/STORY.md` (or `TSnn`) under resolved classic feature root - optional `REFINE/` notes beside it
2. Shortcut: `docs/backlog/<slug>.md` in the **target workspace**

Does **not** create or update cards in external work-item trackers (see `references/exclusions.md`).

## Flow contract: reads, writes, where, when

- **Reads:** the item the operator pastes, or a `STORY.md` or `docs/backlog/` path.
- **Writes:** `STORY.md` with BDD criteria and a quality note; optional `REFINE/` notes beside it.
- **Where:** `features/NNN-slug/USnn/` (preferred) or shortcut `docs/backlog/<slug>.md`.
- **When to use:** an informal backlog item before SDD. Calls `requirement-review` at step 4a before the handoff.

Full flow: [backlog refinement guide](../../../docs/guides/backlog-refine.md).

## Lazy-load

| When | Path |
|------|------|
| Command playbook (step discovery after gates) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/command.md` |
| Mode playbook **feature** (only when mode=feature) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/feature.md` |
| Feature research (orchestrated + mode=feature) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/feature-research.md` |
| Mode playbook **tech** (only when mode=tech) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/tech.md` |
| Mode playbook **split** (only when mode=split) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/split.md` |
| Mode isolation matrix (REQ-004) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/mode-isolation.md` |
| Interaction envelope (REQ-005) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/interaction-envelope.md` |
| Q&A history (REQ-005) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/qa-history.md` |
| Caveman Mode (if active) | `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md` - **Lite cap** |
| Invocation contexts (`direct` vs `orchestrated`, `IC-DIRECT-ORCHESTRATED`) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/INVOCATION-CONTEXTS.md` |
| Selective retrieval (`SR-NO-FULL-DUMP`) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/SELECTIVE-RETRIEVAL.md` |
| Type templates | `skills/_shared/backlog-item-types/{bug,user-story,technical-story}.md` or `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/` after sync |
| Persona / JTBD (optional; User Story / feature mode only) | `references/product-persona.md` → `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/persona-context.md` |
| Product depth / AC budget (scorecard Step 4) | `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/gherkin-budget.md` + `invest-and-story-quality.md` |
| Evidence omit > fabricate (scorecard) | `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/product-evidence-lite.md` |
| Anti-task-shatter (outcome-shaped titles) | `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/anti-task-shatter.md` |
| Clarify depth + severity B/I/MINOR | `{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/clarify-depth.md` |
| Readiness READY / NEEDS_CLARIFICATION | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/readiness-severity.md` |
| Requirement review before handoff (step 4a; owned by `requirement-review`) | `{{TOOLKIT_ROOT}}/skills/requirement-review/SKILL.md` |
| Finding format (id, severity, type, evidence, recommendation) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/finding-format.md` |
| Reference index (routing only) | `{{TOOLKIT_ROOT}}/skills/refine-story/reference.md` |
| Process step detail (lazy) | `{{TOOLKIT_ROOT}}/skills/refine-story/references/<section>.md` |
| Feature storage | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE.md`, `PIPELINE.md` |
| Dynamic manifest / repository-global root resolution (only when resolving storage) | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE-RESOLUTION.md` |
| Story template | `skills/_shared/templates/features/story/STORY.md` |
| Language surfaces (chat vs spawn) | `{{TOOLKIT_ROOT}}/skills/_shared/agents/LANGUAGE.md` |

**Never by default:** do not preload `references/command.md` before Step -1 gates; do **not** preload mode playbooks `feature.md` / `tech.md` / `split.md` until the mode is chosen — load **only** the chosen mode’s playbook; do not preload the other two modes, all `references/*.md`, all backlog-item-types, or `persona-context.md` for Bug/Technical Story. After gates load `references/command.md` for step discovery; then **one** mode playbook + **one** type file + **one** section per step (`SKILL-REFERENCE-RETRIEVAL.md`). Load Product-depth norms only at scorecard Step 4 (or when AC budget is challenged). Do not dump entire `memory-bank/` or full PRD (`SR-NO-FULL-DUMP`).

## Reference routing

| Situation | Path |
|-----------|------|
| Command playbook (step discovery) | `references/command.md` |
| Mode: feature | `references/feature.md` |
| Mode: tech | `references/tech.md` |
| Mode: split | `references/split.md` |
| Mode isolation | `references/mode-isolation.md` |
| Interaction envelope | `references/interaction-envelope.md` |
| Q&A history | `references/qa-history.md` |
| Boundary vs O1 / sdd-spec | `references/boundary.md` |
| Scorecard rubric | `references/scorecard-rubric.md` |
| Scorecard template | `references/scorecard-template.md` |
| Guardrails | `references/guardrails.md` |
| Persistence | `references/persistence.md` |
| Split-story handoff | `references/split-handoff.md` |
| Product persona / JTBD | `references/product-persona.md` → `persona-context.md` |
| Exclusions | `references/exclusions.md` |
| Finding format | `references/finding-format.md` |

## Process

After gates: **Read `references/command.md`** for ordered step discovery. Resolve **refine mode** (`feature` | `tech` | `split`) from invoke or Trigger prompt — then **Read only** `references/<mode>.md` plus `references/mode-isolation.md` (matrix). Do **not** Read the other mode playbooks. Emit/refresh the **interaction envelope** and **Q&A history** per `interaction-envelope.md` / `qa-history.md`. Load `references/<section>.md` for shared procedural detail — **not** full `reference.md`.

### Step -1b - Caveman Mode (Lite cap)
1. Read `{{SDD_ROOT}}/preferences.json` (create `{ "caveman_mode": false, "caveman_level": "full" }` if missing).
2. If `caveman_mode` is false: continue without compression.
3. If true: load `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md`; apply **Lite** participation cap + prefs `caveman_level` (Lite skills never escalate); show once: `[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.`
4. Honor `caveman on|off|status|lite|full|ultra` (and `stop caveman` / `normal mode`) during the session.
5. Auto-Clarity + never-compress gates/drafts/paths per `CAVEMAN.md`.

### 0. Workspace

Confirm **target repository**. Summarize detected stack via Glob if useful.
Resolve `invocation_context` per `INVOCATION-CONTEXTS.md` (`IC-DIRECT-ORCHESTRATED`): default `direct` unless parent handoff marks `orchestrated`. Apply the matching observable table.

Do **not** assume there is no PRD because root `PRD/` is missing - check `features/**/PRD/` (and global `.../features/**/PRD/`) per `STORAGE.md`. Root/flat `PRD/` is not a Classic SDD path.

### 0.5 Refine mode (feature | tech | split)

Resolve mode from the invocation **or** from the user's answer to the Trigger prompt.

| Signal in invoke / reply | Mode | Playbook |
|--------------------------|------|----------|
| `feature` / `1` / User Story or Bug framing | feature | `references/feature.md` |
| `tech` / `technical` / `2` / Technical Story framing | tech | `references/tech.md` |
| `split` / `3` / checklist / topological steps | split | `references/split.md` |

If still unset or value outside `{feature,tech,split}`: on **direct** invocation, **STOP** and ask the Trigger prompt in the user chat language. On **orchestrated** invocation, do not ask; require `mode=feature` or `mode=tech` from the parent. Do not load any mode playbook until the mode is set. Question ids, label rendering, and answer mapping: `{{TOOLKIT_ROOT}}/skills/_shared/agents/QUESTIONS.md`.

Then follow **only** that playbook for collect → generate → mode-specific checks. When `invocation_context=orchestrated` and `mode=feature`, also read `references/feature-research.md`. Apply `references/mode-isolation.md` (no cross-mode leak). Open a skeleton **interaction envelope** (`mode` + `invocation_context` + `status: NEEDS_CLARIFICATION` until READY). Shared scorecard / validation / persistence / handoff sections stay lazy per playbook pointers.

### 1–7. Mode playbook + shared sections

Execute steps inside the chosen `references/<mode>.md`. Typical shared tail (cited from playbook, not preloaded):

| Step | Section |
|------|---------|
| Quality scorecard (Product depth + AC budget) | `references/scorecard-rubric.md` + `references/scorecard-template.md`; lazy `gherkin-budget.md`, `invest-and-story-quality.md`, `product-evidence-lite.md` |
| Requirement review (step 4a, before handoff) | `requirement-review` skill: `--feature`, then `--tech` when the story touches a repository. Pointer only; the review owns its playbooks |
| Envelope + Q&A + READY | `references/interaction-envelope.md`; `references/qa-history.md`; consume `readiness-severity.md` (dual-plane; do not rewrite taxonomy) |
| Validation | `references/guardrails.md` |
| Optional persistence | `references/persistence.md` (+ Q&A history path) |
| Handoff | `references/split-handoff.md`; `references/boundary.md`; `references/exclusions.md` — **portable paths only** |

**Selective retrieval:** do **not** dump entire `memory-bank/` or paste a full PRD into refine chat/handoffs (`SELECTIVE-RETRIEVAL.md` / `SR-NO-FULL-DUMP`). Paths + short summaries only.

## Stage table

You must render the stage table (`_shared/sdd-artifacts/LIVE-STAGE-TABLE.md`, refine-story section) at start, before and after each gate, on each row change, on a blocker, and at close, always with every row. Detail: `references/command.md`.

## Must not

Also enforce `references/exclusions.md`. Boundary: `references/boundary.md`. Product voice: `references/product-persona.md`. Split handoff: `references/split-handoff.md`.

- Call tracker REST APIs, MCP work-item integrations, or PAT scripts for external trackers
- Create or update tracker work items (or any remote board) — file-based persistence only
- Add organization-specific custom fields, mandatory AI tags, or PATCH guardrails for remote boards
- Preload unused mode playbooks (`feature` / `tech` / `split` other than the chosen one) — REQ-004
- Add a second requirement-challenge skill beside `requirement-review`; challenge work is owned there (one skill, two modes). Extend that skill instead
- Write OS absolute paths or InstallRoot embeds into envelopes, Q&A history, or handoffs — portable only (REQ-006 / RNF-002)
- Write `docs/backlog/` before the language question when choosing shortcut
- Duplicate full PRD/PLAN templates - hand off to `sdd-spec` / `sdd-plan` or O1
- Do not dump entire `memory-bank/` or paste full PRD into prompts (`SELECTIVE-RETRIEVAL.md` / `SR-NO-FULL-DUMP`)
- Do not ignore `IC-DIRECT-ORCHESTRATED` — resolve and apply `direct` vs `orchestrated` (`INVOCATION-CONTEXTS.md`)
- Invent architecture that belongs to O1 specialists
- Do not ship vague BDD without challenge
- Do not hand off to `sdd-spec` / claim ready-for-PRD while open clarification **B** or **I** remain — emit `NEEDS_CLARIFICATION` (`readiness-severity.md`); presence ≠ READY (**RN02**); READY ≠ `step_confirmed` (dual-plane / REQ-006)
- Equate envelope `status: READY` with implementation Complete or PLAN step Completed

## Handoff examples

```
/split-story-checklist - features/004-export/US01/STORY.md
```

```
/orchestrate-analyze - features/004-export
```

```
/sdd-spec - features/004-export/US01/STORY.md
```

Cite `REFINE/qa-history.md` in the typed handoff when present — do not paste the full history into the slash line.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall