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):
| Mode | Explicit invoke examples | Default item types |
|---|---|---|
| feature | feature, modo feature, 1 |
User Story or Bug |
| tech | tech, technical, modo tech, 2 |
Technical Story |
| split | split, modo split, 3 |
Any 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):
features/NNN-slug/USnn/STORY.md(orTSnn) under resolved classic feature root - optionalREFINE/notes beside it- Shortcut:
docs/backlog/<slug>.mdin 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.mdordocs/backlog/path. - Writes:
STORY.mdwith BDD criteria and a quality note; optionalREFINE/notes beside it. - Where:
features/NNN-slug/USnn/(preferred) or shortcutdocs/backlog/<slug>.md. - When to use: an informal backlog item before SDD. Calls
requirement-reviewat step 4a before the handoff.
Full flow: backlog refinement guide.
Lazy-load
| When | Path |
|---|---|
| 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 templates | skills/_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 template | skills/_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
| Situation | Path |
|---|---|
| Command playbook (step discovery) | references/command.md |
| Mode: feature | references/feature.md |
| Mode: tech | references/tech.md |
| Mode: split | references/split.md |
| Mode isolation | references/mode-isolation.md |
| Interaction envelope | references/interaction-envelope.md |
| Q&A history | references/qa-history.md |
| Boundary vs O1 / sdd-spec | references/boundary.md |
| Scorecard rubric | references/scorecard-rubric.md |
| Scorecard template | references/scorecard-template.md |
| Guardrails | references/guardrails.md |
| Persistence | references/persistence.md |
| Split-story handoff | references/split-handoff.md |
| Product persona / JTBD | references/product-persona.md → persona-context.md |
| Exclusions | references/exclusions.md |
| Finding format | references/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)
- Read
{{SDD_ROOT}}/preferences.json(create{ "caveman_mode": false, "caveman_level": "full" }if missing). - If
caveman_modeis false: continue without compression. - If true: load
{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md; apply Lite participation cap + prefscaveman_level(Lite skills never escalate); show once:[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar. - Honor
caveman on|off|status|lite|full|ultra(andstop caveman/normal mode) during the session. - 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 / reply | Mode | Playbook |
|---|---|---|
feature / 1 / User Story or Bug framing |
feature | references/feature.md |
tech / technical / 2 / Technical Story framing |
tech | references/tech.md |
split / 3 / checklist / topological steps |
split | references/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):
| Step | Section |
|---|---|
| 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 + READY | references/interaction-envelope.md; references/qa-history.md; consume readiness-severity.md (dual-plane; do not rewrite taxonomy) |
| Validation | references/guardrails.md |
| Optional persistence | references/persistence.md (+ Q&A history path) |
| Handoff | references/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/splitother 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-planor 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 applydirectvsorchestrated(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 — emitNEEDS_CLARIFICATION(readiness-severity.md); presence ≠ READY (RN02); READY ≠step_confirmed(dual-plane / REQ-006) - Equate envelope
status: READYwith 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.