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/scorecard-rubric.md
View on GitHub## Scorecard rubric
Score immediately after generating the markdown. Maximum **100** points. Portable backlog refinement style (no external work-item fields).
**Norms (lazy-load at score time):** `gherkin-budget.md`, `invest-and-story-quality.md`, `product-evidence-lite.md`, `story-sizing.md`. Do not preload the full backlog-item-types folder.
### Universal criteria (all types) — 70 points
| Criterion | Max | Scoring guide |
|-----------|-----|----------------|
| Objective | 12 | 12: affirmative, ≤3 sentences, correct perspective, specific / 7: correct but long or generic / 3: vague or wrong perspective / 0: missing |
| Acceptance criteria (BDD) | 20 | 20: Given/When/Then covering **happy + rule/edge + failure**, each with an **observable Then** (`gherkin-budget.md`) / 12: BDD present but missing one budget slot / 6: single stub or Then not observable / 0: missing |
| Product depth | 10 | 10: Valuable clear + AC budget met + Who/Job/Outcome when US (`n/a` OK for TS/Bug); honest Evidence omission is **not** a fail (`product-evidence-lite.md`) / 6: Valuable weak or AC budget partial / 3: thin product signal / 0: task-shaped or no Valuable |
| Story scope | 10 | 10: one verifiable user/technical outcome (ideally one PR); objective and steps name behavior not files / 5: mostly outcome-oriented but some file/layer fragmentation / 0: file-per-step, layer-per-story, or objective is a file list |
| Implementation steps | 13 | 13: baby steps, infinitive verbs, behavior titles (not file/class only), layer order, explicit deps / 8: steps ok but weak granularity, deps, or file-only titles / 4: generic steps / 0: missing |
| No vague language | 5 | 5: none / 2: 1-2 vague phrases / 0: multiple |
**Story scope contract:** `skills/_shared/backlog-item-types/story-sizing.md`. Penalize step titles that are **only** a file path, class name, or layer label (e.g. "`OrderController.cs`", "Domain layer") — titles must state the behavior or change.
**Product depth contract:** Valuable (`invest-and-story-quality.md`) + AC budget (`gherkin-budget.md`) + Who/Job/Outcome when US. Do **not** deduct for omitted Evidence alone.
### Type-specific criteria (30 points total)
**Technical Story:**
| Criterion | Max |
|-----------|-----|
| Technical context (problem -> solution -> scope) | 10 |
| Repositories / areas listed | 5 |
| Technical specificity (types, endpoints, events when relevant) | 10 |
| Dependencies declared or N/A justified | 5 |
**User Story:**
| Criterion | Max |
|-----------|-----|
| Context + current vs expected flow | 10 |
| Repositories / areas listed | 5 |
| Business AC vs technical AC separated | 10 |
| Dependencies declared or N/A justified | 5 |
**Bug:**
| Criterion | Max |
|-----------|-----|
| Repro steps + evidence | 10 |
| Frequency and impact | 5 |
| Suggested fix steps with files and deps | 10 |
| Non-regression BDD scenario | 5 |
### Map /100 and Product depth → STORY 1–5
**Overall total** (for chat summary / Clareza–Testabilidade composites when needed):
| Band (/100) | STORY 1–5 |
|-------------|-----------|
| 80–100 | 5 |
| 60–79 | 4 |
| 40–59 | 3 |
| 1–39 | 2 |
| 0 | leave blank or 0 |
**Product depth criterion** (max 10) → STORY **Product depth** row:
| Score (/10) | STORY 1–5 |
|-------------|-----------|
| 9–10 | 5 |
| 7–8 | 4 |
| 5–6 | 3 |
| 3–4 | 2 |
| 1–2 | 1 |
| 0 | 0 / blank |
Minimum AC budget (happy + rule/edge + failure with observable Then) must hold before Product depth can score above **6**.
Do not invent a baseline, a target, or a date when the source did not bring one.
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 |