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/split.md
View on GitHub# Mode playbook: split
**Load only when refine mode = `split`.** Do not load `feature.md` or `tech.md` in the same session step. Isolation matrix: `references/mode-isolation.md`.
Mode playbook: prepare dependency-aware steps for a local checklist split (not work-item decomposition in a tracker). Requirement challenge is not part of this mode; see `requirement-review`.
## Scope
Produce or reshape a refined item so **implementation steps** are ready for `/split-story-checklist`: one responsibility per step, explicit deps, parallel-safe notes, outcome-shaped titles.
May start from: pasted draft, existing `STORY.md` / `docs/backlog/` path, or a short description. Item type may be Bug, User Story, or Technical Story — load **one** matching type file only.
**Envelope:** `mode: split` — see `references/interaction-envelope.md`. Chat prefix: `[Refine · split]`. Default `handoff_candidate`: `split-story-checklist`. Include a short steps-readiness note in the envelope.
## Steps
### 1. Resolve source + type
Ask once if missing:
```
[Refine · split] Fonte e tipo?
1) Colar / descrever agora
2) Path STORY.md ou docs/backlog/
Tipo: Bug | User Story | Technical Story
```
Load **one** type template from `_shared/backlog-item-types/`. For User Story persona only when Who/Job/Outcome helps (`references/product-persona.md`). Do **not** run the full `feature` or `tech` playbooks — stay on split-focused shaping.
Open/refresh skeleton envelope (`mode: split`, `item_type`, `status: NEEDS_CLARIFICATION` until READY).
### 2. Collect or read existing body
If path given: Read that file (portable path only). If thin: ask targeted questions for missing Objective, AC, or steps — do not invent full product context beyond what split needs. Append clarifications to Q&A history (`references/qa-history.md`).
### 3. Generate / reshape documentation
Ensure sections required by the type template exist. **Primary focus — Steps:**
- One responsibility per step; infinitive verbs
- Behavior titles — not file/class/layer-only (`story-sizing.md`, `anti-task-shatter.md`)
- Explicit `Depends on:` (or clear “none”) for topological grouping
- Mark independent steps as parallel-safe when true
- Layer order when applicable
**BDD:** keep or add Given/When/Then with AC budget **happy + rule/edge + failure** and observable Then. Challenge vagueness.
**Selective retrieval:** do not dump bank/PRD (`SR-NO-FULL-DUMP`).
This mode does **not** call `split-story-checklist` internals — it prepares input and hands off.
### 4. Quality scorecard
Score per `references/scorecard-rubric.md` + `references/scorecard-template.md`. Lazy-load Product-depth norms. Emphasize **Implementation steps** and **Story scope** notes for checklist readiness. Product depth wiring preserved (US03). Show in chat the total / 100, ALL criteria rows, strengths, and improvements immediately after the markdown. The full scorecard is chat-only; persistence keeps only the short summary.
Refresh envelope `status` per `readiness-severity.md`; set `handoff_candidate: split-story-checklist` when steps are checklist-ready.
### 5. Validation (chat-only)
Check `references/guardrails.md` — especially deps and outcome-shaped step titles.
### 6. Optional persistence
Follow `references/persistence.md`. Persist Q&A history when saving. File-based only — never Azure WI / external tracker (`references/exclusions.md`).
### 7. Handoff (required offer)
Always offer (portable path):
```
/split-story-checklist - <portable-story-or-backlog-path>
```
Detail: `references/split-handoff.md`. Other paths: O1 / `sdd-spec` / stack developer per `references/boundary.md` — only when envelope `status` is **READY** for that target (`readiness-severity.md`).
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 |