Skip to content

tibursocampos/agent-dev-toolkit / core/skills/refine-story

refine-story

Verified

Refine 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.

STOP - Read before ANY tool call

Read _shared/skill-boilerplate.md first. It holds the guardrails read, the session gate rule, the user sim rule, the one-step rule, the gate check, and the user chat language rule. The steps below are skill-specific only.

Skill: refine-story

Trigger

Negative signal: applies as defined in _shared/skill-boilerplate.md; the skill-specific signals are listed below.

Invoke when the user asks for: /refine-story, refine backlog item, or quick intake before SDD / Orchestrated Delivery.

Optional: path to existing notes, pasted description, or explicit mode (feature | tech | split).

Refine mode (mandatory — no silent default):

ModeExplicit invoke examplesDefault item types
featurefeature, modo feature, 1User Story or Bug
techtech, technical, modo tech, 2Technical Story
splitsplit, modo split, 3Any type — split-ready steps + checklist handoff

If the invocation does not name a mode: STOP after gate check (-1) / before deep refine and ask once, in the user chat language, then wait. Do not assume feature. Do not load any mode playbook until answered.

That question applies only to direct invocation. When invocation_context=orchestrated, the parent passes mode=feature or mode=tech. Do not ask the mode. Load that playbook. For mode=feature, also load references/feature-research.md (references/feature.md).

Question component form (ids fixed in English; labels rendered in the user chat language):

header: refine-story mode
question: refine-story mode?
single select:
- feature: User Story or Bug framing
- tech: Technical Story framing
- split: steps ready for /split-story-checklist

Render the question and the three labels in the user chat language. Keep the mode ids feature, tech, and split in English. The descriptions above give the meaning of each id; they are not labels to copy.

Outcome

Structured markdown in chat (BDD acceptance criteria + implementation steps) and a quality scorecard aligned to portable backlog refinement patterns.

Persistence (prefer in order):

  1. features/NNN-slug/USnn/STORY.md (or TSnn) under resolved classic feature root - optional REFINE/ notes beside it
  2. Shortcut: docs/backlog/<slug>.md in the target workspace

Does not create or update cards in external work-item trackers (see references/exclusions.md).

Flow contract: reads, writes, where, when

  • Reads: the item the operator pastes, or a STORY.md or docs/backlog/ path.
  • Writes: STORY.md with BDD criteria and a quality note; optional REFINE/ notes beside it.
  • Where: features/NNN-slug/USnn/ (preferred) or shortcut docs/backlog/<slug>.md.
  • When to use: an informal backlog item before SDD. Calls requirement-review at step 4a before the handoff.

Full flow: backlog refinement guide.

Lazy-load

WhenPath
Command playbook (step discovery after gates){{TOOLKIT_ROOT}}/skills/refine-story/references/command.md
Mode playbook feature (only when mode=feature){{TOOLKIT_ROOT}}/skills/refine-story/references/feature.md
Feature research (orchestrated + mode=feature){{TOOLKIT_ROOT}}/skills/refine-story/references/feature-research.md
Mode playbook tech (only when mode=tech){{TOOLKIT_ROOT}}/skills/refine-story/references/tech.md
Mode playbook split (only when mode=split){{TOOLKIT_ROOT}}/skills/refine-story/references/split.md
Mode isolation matrix (REQ-004){{TOOLKIT_ROOT}}/skills/refine-story/references/mode-isolation.md
Interaction envelope (REQ-005){{TOOLKIT_ROOT}}/skills/refine-story/references/interaction-envelope.md
Q&A history (REQ-005){{TOOLKIT_ROOT}}/skills/refine-story/references/qa-history.md
Caveman Mode (if active){{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md - Lite cap
Invocation contexts (direct vs orchestrated, IC-DIRECT-ORCHESTRATED){{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/INVOCATION-CONTEXTS.md
Selective retrieval (SR-NO-FULL-DUMP){{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/SELECTIVE-RETRIEVAL.md
Type templatesskills/_shared/backlog-item-types/{bug,user-story,technical-story}.md or {{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/ after sync
Persona / JTBD (optional; User Story / feature mode only)references/product-persona.md → {{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/persona-context.md
Product depth / AC budget (scorecard Step 4){{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/gherkin-budget.md + invest-and-story-quality.md
Evidence omit > fabricate (scorecard){{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/product-evidence-lite.md
Anti-task-shatter (outcome-shaped titles){{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/anti-task-shatter.md
Clarify depth + severity B/I/MINOR{{TOOLKIT_ROOT}}/skills/_shared/backlog-item-types/clarify-depth.md
Readiness READY / NEEDS_CLARIFICATION{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/readiness-severity.md
Requirement review before handoff (step 4a; owned by requirement-review){{TOOLKIT_ROOT}}/skills/requirement-review/SKILL.md
Finding format (id, severity, type, evidence, recommendation){{TOOLKIT_ROOT}}/skills/refine-story/references/finding-format.md
Reference index (routing only){{TOOLKIT_ROOT}}/skills/refine-story/reference.md
Process step detail (lazy){{TOOLKIT_ROOT}}/skills/refine-story/references/<section>.md
Feature storage{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE.md, PIPELINE.md
Dynamic manifest / repository-global root resolution (only when resolving storage){{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE-RESOLUTION.md
Story templateskills/_shared/templates/features/story/STORY.md
Language surfaces (chat vs spawn){{TOOLKIT_ROOT}}/skills/_shared/agents/LANGUAGE.md

Never by default: do not preload references/command.md before Step -1 gates; do not preload mode playbooks feature.md / tech.md / split.md until the mode is chosen — load only the chosen mode’s playbook; do not preload the other two modes, all references/*.md, all backlog-item-types, or persona-context.md for Bug/Technical Story. After gates load references/command.md for step discovery; then one mode playbook + one type file + one section per step (SKILL-REFERENCE-RETRIEVAL.md). Load Product-depth norms only at scorecard Step 4 (or when AC budget is challenged). Do not dump entire memory-bank/ or full PRD (SR-NO-FULL-DUMP).

Reference routing

SituationPath
Command playbook (step discovery)references/command.md
Mode: featurereferences/feature.md
Mode: techreferences/tech.md
Mode: splitreferences/split.md
Mode isolationreferences/mode-isolation.md
Interaction envelopereferences/interaction-envelope.md
Q&A historyreferences/qa-history.md
Boundary vs O1 / sdd-specreferences/boundary.md
Scorecard rubricreferences/scorecard-rubric.md
Scorecard templatereferences/scorecard-template.md
Guardrailsreferences/guardrails.md
Persistencereferences/persistence.md
Split-story handoffreferences/split-handoff.md
Product persona / JTBDreferences/product-persona.md → persona-context.md
Exclusionsreferences/exclusions.md
Finding formatreferences/finding-format.md

Process

After gates: Read references/command.md for ordered step discovery. Resolve refine mode (feature | tech | split) from invoke or Trigger prompt — then Read only references/<mode>.md plus references/mode-isolation.md (matrix). Do not Read the other mode playbooks. Emit/refresh the interaction envelope and Q&A history per interaction-envelope.md / qa-history.md. Load references/<section>.md for shared procedural detail — not full reference.md.

Step -1b - Caveman Mode (Lite cap)

  1. Read {{SDD_ROOT}}/preferences.json (create { "caveman_mode": false, "caveman_level": "full" } if missing).
  2. If caveman_mode is false: continue without compression.
  3. If true: load {{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md; apply Lite participation cap + prefs caveman_level (Lite skills never escalate); show once: [Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.
  4. Honor caveman on|off|status|lite|full|ultra (and stop caveman / normal mode) during the session.
  5. Auto-Clarity + never-compress gates/drafts/paths per CAVEMAN.md.

0. Workspace

Confirm target repository. Summarize detected stack via Glob if useful. Resolve invocation_context per INVOCATION-CONTEXTS.md (IC-DIRECT-ORCHESTRATED): default direct unless parent handoff marks orchestrated. Apply the matching observable table.

Do not assume there is no PRD because root PRD/ is missing - check features/**/PRD/ (and global .../features/**/PRD/) per STORAGE.md. Root/flat PRD/ is not a Classic SDD path.

0.5 Refine mode (feature | tech | split)

Resolve mode from the invocation or from the user's answer to the Trigger prompt.

Signal in invoke / replyModePlaybook
feature / 1 / User Story or Bug framingfeaturereferences/feature.md
tech / technical / 2 / Technical Story framingtechreferences/tech.md
split / 3 / checklist / topological stepssplitreferences/split.md

If still unset or value outside {feature,tech,split}: on direct invocation, STOP and ask the Trigger prompt in the user chat language. On orchestrated invocation, do not ask; require mode=feature or mode=tech from the parent. Do not load any mode playbook until the mode is set. Question ids, label rendering, and answer mapping: {{TOOLKIT_ROOT}}/skills/_shared/agents/QUESTIONS.md.

Then follow only that playbook for collect → generate → mode-specific checks. When invocation_context=orchestrated and mode=feature, also read references/feature-research.md. Apply references/mode-isolation.md (no cross-mode leak). Open a skeleton interaction envelope (mode + invocation_context + status: NEEDS_CLARIFICATION until READY). Shared scorecard / validation / persistence / handoff sections stay lazy per playbook pointers.

1–7. Mode playbook + shared sections

Execute steps inside the chosen references/<mode>.md. Typical shared tail (cited from playbook, not preloaded):

StepSection
Quality scorecard (Product depth + AC budget)references/scorecard-rubric.md + references/scorecard-template.md; lazy gherkin-budget.md, invest-and-story-quality.md, product-evidence-lite.md
Requirement review (step 4a, before handoff)requirement-review skill: --feature, then --tech when the story touches a repository. Pointer only; the review owns its playbooks
Envelope + Q&A + READYreferences/interaction-envelope.md; references/qa-history.md; consume readiness-severity.md (dual-plane; do not rewrite taxonomy)
Validationreferences/guardrails.md
Optional persistencereferences/persistence.md (+ Q&A history path)
Handoffreferences/split-handoff.md; references/boundary.md; references/exclusions.md — portable paths only

Selective retrieval: do not dump entire memory-bank/ or paste a full PRD into refine chat/handoffs (SELECTIVE-RETRIEVAL.md / SR-NO-FULL-DUMP). Paths + short summaries only.

Stage table

You must render the stage table (_shared/sdd-artifacts/LIVE-STAGE-TABLE.md, refine-story section) at start, before and after each gate, on each row change, on a blocker, and at close, always with every row. Detail: references/command.md.

Must not

Also enforce references/exclusions.md. Boundary: references/boundary.md. Product voice: references/product-persona.md. Split handoff: references/split-handoff.md.

  • Call tracker REST APIs, MCP work-item integrations, or PAT scripts for external trackers
  • Create or update tracker work items (or any remote board) — file-based persistence only
  • Add organization-specific custom fields, mandatory AI tags, or PATCH guardrails for remote boards
  • Preload unused mode playbooks (feature / tech / split other than the chosen one) — REQ-004
  • Add a second requirement-challenge skill beside requirement-review; challenge work is owned there (one skill, two modes). Extend that skill instead
  • Write OS absolute paths or InstallRoot embeds into envelopes, Q&A history, or handoffs — portable only (REQ-006 / RNF-002)
  • Write docs/backlog/ before the language question when choosing shortcut
  • Duplicate full PRD/PLAN templates - hand off to sdd-spec / sdd-plan or O1
  • Do not dump entire memory-bank/ or paste full PRD into prompts (SELECTIVE-RETRIEVAL.md / SR-NO-FULL-DUMP)
  • Do not ignore IC-DIRECT-ORCHESTRATED — resolve and apply direct vs orchestrated (INVOCATION-CONTEXTS.md)
  • Invent architecture that belongs to O1 specialists
  • Do not ship vague BDD without challenge
  • Do not hand off to sdd-spec / claim ready-for-PRD while open clarification B or I remain — emit NEEDS_CLARIFICATION (readiness-severity.md); presence ≠ READY (RN02); READY ≠ step_confirmed (dual-plane / REQ-006)
  • Equate envelope status: READY with implementation Complete or PLAN step Completed

Handoff examples

/split-story-checklist - features/004-export/US01/STORY.md
/orchestrate-analyze - features/004-export
/sdd-spec - features/004-export/US01/STORY.md

Cite REFINE/qa-history.md in the typed handoff when present — do not paste the full history into the slash line.

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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall