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/interaction-envelope.md
View on GitHub# Interaction envelope (per refine mode)
**REQ-005 / CA2.** Every refine session that reaches collect/generate emits a typed **interaction envelope**. Shape is mode-scoped: fields that belong to another mode stay omitted (REQ-004).
## Canonical shape (English keys; portable paths only)
```yaml
schema: refine-story.interaction_envelope/v1
mode: feature # feature | tech | split — MUST match active playbook
invocation_context: direct # direct | orchestrated (INVOCATION-CONTEXTS.md)
item_type: User Story # Bug | User Story | Technical Story
status: NEEDS_CLARIFICATION # READY | NEEDS_CLARIFICATION (readiness-severity.md)
portable_paths:
story: features/NNN-slug/USnn/STORY.md # omit until known
refine_notes: features/NNN-slug/USnn/REFINE/refine.md
qa_history: features/NNN-slug/USnn/REFINE/qa-history.md
open_questions:
- severity: B
text: "<sharp question>"
- severity: I
text: "<sharp question>"
minor_questions:
- severity: MINOR
text: "<optional>"
qa_history_ref: features/NNN-slug/USnn/REFINE/qa-history.md
handoff_candidate: sdd-spec # split-story-checklist | orchestrate-analyze | sdd-spec | none
```
**Portable paths only** (`STORAGE.md` § Portable path / RNF-002 / REQ-006). Forbidden in envelopes and handoffs: OS absolute paths (drive-letter or UNC) and InstallRoot embeds under the tool’s `sdd` session root.
## Mode-scoped field rules
| Field / behavior | `feature` | `tech` | `split` |
|------------------|-----------|--------|---------|
| `mode` token | `feature` | `tech` | `split` |
| `item_type` | User Story \| Bug | Technical Story | Any one resolved type |
| Default `handoff_candidate` when READY | `sdd-spec` (or `split-story-checklist` if steps are the ask) | same | **prefer** `split-story-checklist` |
| Persona notes in envelope | optional short Who/Job | omit | only if User Story |
| Steps-readiness note | optional | optional | **required** short note: deps + parallel-safe |
Do **not** attach foreign mode playbook rules inside the envelope body.
## When to emit
| Moment | Action |
|--------|--------|
| After mode resolved (0.5) | Skeleton envelope (`mode`, `invocation_context`, `status: NEEDS_CLARIFICATION` until scored) |
| After scorecard / clarification pass | Refresh `status`, `open_questions`, `portable_paths` |
| On handoff / STOP | Full envelope + Q&A history pointer (`qa-history.md`) |
## Dual-plane READY (consume 006 — do not rewrite)
Status tokens and B/I/MINOR taxonomy: `_shared/sdd-artifacts/readiness-severity.md` only.
| Envelope `status` | Meaning |
|-------------------|---------|
| **READY** | Per `readiness-severity.md`; may hand off to `/sdd-spec` / O2 path |
| **NEEDS_CLARIFICATION** | Per `readiness-severity.md`; **STOP** fake-forward ready-for-PRD |
**READY ≠** SESSION `step_confirmed` / PLAN step Complete / folder presence (**RN02**, `RDY-DUAL-PLANE`). Do not reopen taxonomy scripts in this enrich step.
## Chat report (session user language; English tokens)
```text
Envelope refine-story
mode: feature
status: READY | NEEDS_CLARIFICATION
paths: <portable only>
open B/I/MINOR: <count>
qa_history: <portable path or "(chat-only — not persisted)">
next: <handoff or answer B/I>
```
## Related
| Topic | Path |
|-------|------|
| Mode isolation | `references/mode-isolation.md` |
| Q&A history | `references/qa-history.md` |
| Boundary STOP | `references/boundary.md` |
| Persistence | `references/persistence.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 |