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/feature.md
View on GitHub# Mode playbook: feature
When `invocation_context=orchestrated`, do not ask the mode and load `references/feature-research.md`.
**Load only when refine mode = `feature`.** Do not load `tech.md` or `split.md` in the same session step. Isolation matrix: `references/mode-isolation.md`.
Mode playbook: local markdown refine, no remote tracker. Requirement challenge for feature items is owned by `requirement-review --feature`, which runs at step 4a; do not duplicate it here.
## Scope
Product-facing backlog: **User Story** or **Bug**. Prefer User Story when value/outcome is primary; Bug when defect reproduction is primary.
**Envelope:** `mode: feature` — see `references/interaction-envelope.md`. Chat prefix: `[Refine · feature]`.
## Steps
### 1. Select item type (within feature)
```
[Refine · feature] Tipo?
1) User Story
2) Bug
```
Load **one** matching file from `_shared/backlog-item-types/` (`user-story.md` or `bug.md`). Map: User Story → `USnn`; Bug → prefer `USnn` or note under existing story.
For User Story when who/job/outcome helps: load `references/product-persona.md` (points at `persona-context.md`). Do **not** load `technical-story.md` in this mode unless the user explicitly switches to `tech`.
Open/refresh skeleton envelope (`item_type`, `status: NEEDS_CLARIFICATION` until READY).
### 2. Collect description
Ask for free-form description (problem, goal, context, constraints). Wait for enough detail; if thin, use collection questions from the type file — do not ship placeholder `[...]` sections.
When asking clarification questions: append to Q&A history (`references/qa-history.md`) before waiting; tag **B** \| **I** \| **MINOR** (`clarify-depth.md` / `readiness-severity.md`).
### 3. Generate documentation
Follow the type file **Output template** and **Writing guidelines**. Combine user input with structure from the template — calibrate depth, not copy corporate examples.
**Steps:** one responsibility per step; infinitive verbs; layer order when applicable; explicit dependencies; note parallel steps when independent (feeds later `split` mode / `split-story-checklist`).
**BDD:** **Given / When / Then / And**; verifiable outcomes; **challenge vagueness** — avoid "works correctly", "as expected", "properly", "funciona corretamente". When handing off to `sdd-spec`, note that PRD will require stable **REQ-IDs**, OOS, and verifiable CA (`templates/sdd/PRD.md`).
**Selective retrieval:** paths + short summaries only (`SR-NO-FULL-DUMP`).
### 4. Quality scorecard
Immediately after the markdown, score per `references/scorecard-rubric.md` + `references/scorecard-template.md`. Lazy-load `gherkin-budget.md` + `invest-and-story-quality.md` (and `product-evidence-lite.md` when Evidence is discussed). Score **Product depth** and verify AC budget (**happy + rule/edge + failure**, observable Then). Show in chat the total / 100, ALL criteria rows (not a subset), strengths, and specific improvements. The full scorecard is chat-only; persistence keeps only the short `Scorecard (resumo)` (`scorecard-template.md`). Map Product depth → STORY 1–5 per rubric.
Refresh envelope `status` from open questions. At the refine→PRD/O2 handoff, READY means no unanswered **B**/**I**/**MINOR** (`open_question`). An unanswered `MINOR` is blocking at that gate; it is not an assumption that may be carried forward.
### 5. Validation (chat-only)
Before presenting as final, check `references/guardrails.md`.
### 6. Optional persistence
Follow `references/persistence.md`. Persist Q&A history when saving (`qa-history.md`). File-based only — never Azure WI / external tracker (`references/exclusions.md`).
### 7. Handoff
| Situation | Next |
|-----------|------|
| Break into implementation checklist | Offer mode `split` or `/split-story-checklist - <portable-story-path>` |
| Multi-story / complex | `/orchestrate-analyze - <portable-feature-path>` |
| READY for PRD (no unanswered question, including `MINOR`, at the open-question gate) | `/sdd-spec - <portable-story-path>` |
| NEEDS_CLARIFICATION / `open_question` | Answer every open question; cite `qa_history` portable path — do **not** claim ready-for-PRD |
| Small isolated change | `/developer` / stack `*-developer` |
Boundary detail: `references/boundary.md`. Portable paths only (REQ-006 / RNF-002).
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 |