Refine Story

STOP - Read before ANY tool call

1. Read {{GUARDRAILS_PATH}}
2. Read _shared/sdd-artifacts/SESSION.md; load session-state for $Cwd
3. If the relevant gate is not approved: STOP - ask user (pt-BR) - do NOT Write/Shell
4. SDD/develop skills: after ONE step/task, STOP session - handoff only
5. This skill body is English; user-facing prompts may be (pt-BR)

Step -1 - Gate check (report in chat before continuing)

Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] PIPELINE.md read (SDD skills only)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP

Skill: refine-story

Trigger

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):

If the invocation does not name a mode: STOP after gate check (-1) / before deep refine — ask once (pt-BR) and wait. Do not assume feature. Do not load any mode playbook until answered.

Modo de refine-story?
1) feature - User Story / Bug (produto)
2) tech - Technical Story
3) split - passos prontos para /split-story-checklist

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

Lazy-load

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

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. Do not Read the other mode playbooks. 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.

If still unset or value outside {feature,tech,split}: STOP — ask the Trigger prompt (pt-BR) — do not load any mode playbook until answered.

Then follow only that playbook for collect → generate → mode-specific checks. 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):

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.

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 Azure DevOps 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)
• 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

Handoff examples

/split-story-checklist - features/004-export/US01/STORY.md

/orchestrate-analyze

/sdd-spec