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/tech.md
View on GitHub# Mode playbook: tech
**Load only when refine mode = `tech`.** Do not load `feature.md` or `split.md` in the same session step. Isolation matrix: `references/mode-isolation.md`.
Mode playbook: local markdown refine for technical work, no remote tracker. Repository-grounded technical challenge is owned by `requirement-review --tech`, which runs at step 4a.
## Scope
**Technical Story** only (`TSnn`). Problem → solution → scope; repositories/areas; technical specificity (types, endpoints, events when relevant).
**Envelope:** `mode: tech` — see `references/interaction-envelope.md`. Chat prefix: `[Refine · tech]`.
## Steps
### 1. Confirm Technical Story
Default type = Technical Story. Load `_shared/backlog-item-types/technical-story.md` only.
Do **not** load `user-story.md`, `bug.md`, or `persona-context.md` in this mode unless the user explicitly switches to `feature`.
Map persistence to `features/NNN-slug/TSnn/STORY.md` when saving under features.
Open/refresh skeleton envelope (`item_type: Technical Story`, `status: NEEDS_CLARIFICATION` until READY).
### 2. Collect description
Ask for technical problem, proposed direction, affected areas, constraints, and known dependencies. Use collection questions from `technical-story.md` when thin — no placeholder `[...]` sections.
When clarifying: append Q&A history (`references/qa-history.md`); severity **B** \| **I** \| **MINOR**.
### 3. Generate documentation
Follow `technical-story.md` **Output template** and **Writing guidelines**.
**Steps:** one responsibility per step; infinitive verbs; behavior titles (not file/class only — `story-sizing.md` / `anti-task-shatter.md`); layer order; explicit `Depends on:`; mark parallel-safe steps.
**BDD:** technical acceptance as Given/When/Then with observable Then; cover **happy + rule/edge + failure** (`gherkin-budget.md`). Challenge vague language.
**Selective retrieval:** paths + short summaries only (`SR-NO-FULL-DUMP`). Do not invent architecture that belongs to O1 specialists (`references/boundary.md`).
### 4. Quality scorecard
Score per `references/scorecard-rubric.md` + `references/scorecard-template.md`. Lazy-load Product-depth norms at score time. For Technical Story, Who/Job/Outcome is **`n/a`** — still score Product depth via Valuable + AC budget (`invest-and-story-quality.md`). Evidence omit OK (`product-evidence-lite.md`). 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` (envelope shape: `interaction-envelope.md`).
### 5. Validation (chat-only)
Check `references/guardrails.md` (Technical Story rows).
### 6. Optional persistence
Follow `references/persistence.md`. Prefer `features/.../TSnn/STORY.md`. Persist Q&A history when saving. File-based only — never Azure WI / external tracker (`references/exclusions.md`).
### 7. Handoff
| Situation | Next |
|-----------|------|
| Dependency-aware checklist | Offer mode `split` or `/split-story-checklist - <portable-story-path>` |
| Multi-story / needs specialists | `/orchestrate-analyze - <portable-feature-path>` |
| READY for PRD (no unanswered question at the open-question gate, including `MINOR`) | `/sdd-spec - <portable-story-path>` |
| `open_question` | Answer every open question; cite `qa_history` — do **not** claim ready-for-PRD |
| Isolated implementation | stack `*-developer` / `/developer` |
Portable paths only (REQ-006 / RNF-002).
## Story PRD contestation
Apply this section to a story PRD after `sdd-spec` writes it. Do not apply it to a feature-level spec. The Technical Story playbook above stays in force for `mode=tech`. This section does not replace it.
Inspect the PRD for API, events, database, and domain, and for coherence across those four. Record findings with `finding-format.md`.
Then run one contestation pass, isolated from the first:
- Already answered by another section or by repository evidence you can cite.
- Severity inflated by asking for implementation detail the PRD does not owe.
- A recommendation that would break an existing contract or duplicate a surface.
- A contradiction between two of the four areas that the first pass missed.
An open question after contestation means the PRD is not accepted. Stop code `open_question`. Do not call `sdd-plan`. Ask every open question. The block limit does not apply.
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 |