tibursocampos/agent-dev-toolkit / core/skills/refine-story
refine-story
VerifiedRefine 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.1 KB |
| reference.md | markdown | 2.4 KB |
| references/boundary.md | markdown | 3.7 KB |
| references/command.md | markdown | 3.5 KB |
| references/exclusions.md | markdown | 1.1 KB |
| references/feature-research.md | markdown | 4.2 KB |
| references/feature.md | markdown | 4.2 KB |
| references/finding-format.md | markdown | 2.7 KB |
| references/guardrails.md | markdown | 2.2 KB |
| references/interaction-envelope.md | markdown | 3.4 KB |
| references/mode-isolation.md | markdown | 2.4 KB |
| references/persistence.md | markdown | 1.3 KB |
| references/product-persona.md | markdown | 955 B |
| references/qa-history.md | markdown | 4.1 KB |
| references/scorecard-rubric.md | markdown | 3.5 KB |
| references/scorecard-template.md | markdown | 2.2 KB |
| references/split-handoff.md | markdown | 797 B |
| references/split.md | markdown | 3.7 KB |
| references/tech.md | markdown | 4.4 KB |
references/boundary.md
View on GitHub## Boundary: refine vs O1 vs sdd-spec
| Aspect | `refine-story` (Backlog Refine) | `orchestrate-analyze` (O1) | `sdd-spec` (Classic SDD) |
|--------|----------------------------------|----------------------------|----------------------|
| Purpose | Fast intake - one backlog item + scorecard + envelope/Q&A | Multi-agent triage + US/TS backlog for a feature | Full PRD for one story/feature |
| Output | Structured markdown + scorecard + interaction envelope | `FEATURE.md`, `CONTINUITY.md`, `STORY.md` × N | PRD under `features/.../PRD/` |
| Persistence | Prefer `features/.../STORY.md` + `REFINE/qa-history.md`; shortcut `docs/backlog/` | Feature tree only | Canonical PRD path |
| Specialists | None | Conditional Agent (`needs_*`) | None (consumes Prior context) |
| When to use | Informal idea, bug, single TS/US | Complex / multi-story / brownfield package | Ready to write PRD for one path |
| Tracker | Never (no external tracker/`az`) | Never | Never |
Escalate to **O1** when: multiple stories, unclear flags (`needs_*`), brownfield impact needs parallel specialists.
Escalate to **sdd-spec** when: single story is clear enough for a PRD (or after refine approval) **and** clarification status is **READY** (no unanswered **B**/**I**/**MINOR** at the refine→PRD gate — consume `readiness-severity.md`; REQ-006). PRD contract (REQ-IDs, verifiable CA, OOS, optional hybrid EARS) lives in `templates/sdd/PRD.md` — refine does **not** invent a parallel PRD body.
### Clarification STOP (REQ-004–006 / TE01)
Open questions use severity **B** \| **I** \| **MINOR** (`clarify-depth.md` + `readiness-severity.md`). Taxonomy + dual-plane SoT stays in **006** contract — **consume**, do not rewrite Assert PS1.
| Status | Refine behavior |
|--------|-----------------|
| **READY** | May hand off to `/sdd-spec` / O2 only when no unanswered **B**/**I**/**MINOR** remains at the open-question gate; envelope `status: READY` |
| **NEEDS_CLARIFICATION** | **STOP** fake-forward “approved for PRD”; do **not** tell operator the item is ready for `sdd-spec` / O2 Write; emit typed handoff (portable paths + B/I list + `qa_history` ref) |
**RN02:** sibling folder presence ≠ READY. **Dual plane (REQ-006):** clarification READY ≠ SESSION `step_confirmed` / implementation Complete / PLAN step Completed.
**Mode isolation (REQ-004):** active mode playbook only — `mode-isolation.md`. Envelope `mode` must match.
**Envelopes + Q&A (REQ-005):** `interaction-envelope.md` + `qa-history.md`.
**Requirement challenge:** `requirement-review` owns feature and tech challenge (one skill, two modes). Refine calls it before handoff. Do not create a second challenge skill or a `feature-refinement` folder.
**Selective retrieval:** `SELECTIVE-RETRIEVAL.md` rule `SR-NO-FULL-DUMP` — **must not** dump entire `memory-bank/` or paste full PRD into refine output/handoffs. Smoke: `Assert-CoreContracts.ps1` (SelectiveRetrieval section).
Do **not** expand refine into a full PRD inline.
Handoff wording (portable paths only — RNF-002):
```
Item grande / multi-história: /orchestrate-analyze - features/NNN-slug
Item único READY para PRD: /sdd-spec - features/NNN-slug/USnn/STORY.md
NEEDS_CLARIFICATION (B/I/MINOR abertos): responder perguntas — qa_history: features/…/REFINE/qa-history.md — não /sdd-spec ainda
Checklist local: /split-story-checklist - features/NNN-slug/USnn/STORY.md
```
Before suggesting `sdd-spec`, optionally Glob `features/**/PRD/` (workspace + global feature root) per `STORAGE.md`. Do **not** glob root/flat `PRD/` for execution.
`sdd-spec` owns storage choice, manifest, `.gitignore`, and confirm-before-write. Refine does **not** write PRD/PLAN. Promote `docs/backlog/` via `sdd-spec` or O1 - never treat backlog files as PRD.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |