القائمة
Use when the user wants to implement a single story or deliver a backlog item.
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/joris887/exosuit --skill story-cycleيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
Execute comprehensive backlog review. Analyzes story quality, Definition of Ready compliance, dependencies, zombie stories, and generates a backlog health report.
First-run framework setup. Detects existing project stack or guides new project creation from vision/braindump.
Use when the user has a complex idea that needs design exploration before story decomposition.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | story-cycle |
| version | 4.4.0 |
| description | Use when the user wants to implement a single story or deliver a backlog item. |
| trigger | manual |
| depends-on | ["code-quality","test-validator","security-audit"] |
| requires | ["git"] |
| optional-requires | ["test-command","lint-command","typecheck-command"] |
| references | ["references/story-types.md","references/self-review.md","references/disaster-prevention.md","references/reasoning-tools.md","references/elicitation-techniques.md","references/error-recovery.md","references/plan-template.md","references/parallel-streams.md"] |
| micro-components | {"phase-0":["context-prime"],"phase-1":["discover-commands","verify-clean-git-state","wave-execution","grep-first-explore"],"phase-2":["confidence-gate"],"phase-4":["record-failure","quality-gate-sequence","capture-learnings","capture-outcome"]} |
| disable-model-invocation | true |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Bash, Edit, Write, WebSearch, WebFetch, Agent |
| argument-hint | <story-description-or-id> |
Delivering story: $ARGUMENTS
Skill metrics: Emit a start event to the activity log:
echo "{\"type\":\"skill\",\"event\":\"start\",\"skill\":\"story-cycle\",\"story\":\"$ARGUMENTS\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl
Progress tracking: At the start, create a task list for phase tracking:
At each phase boundary, mark the current task completed and the next task in_progress.
START → Phase 0: Intent Decomposition (identify ALL deliverables, mark uncertainties)
→ Size Classification:
→ [TRIVIAL: single-file, <10 lines, no behavioral change]
→ Phase 3-lite: Make change → Run tests → Abbreviated self-review → Commit → DONE
→ [SMALL: single-file, <50 lines, clear AC]
→ Lightweight Phase 1 (skip 1f-1g) → Phase 2 → Phase 3 → Phase 4 → DONE
→ [STANDARD: everything else]
→ Phase 1: Plan Mode (research, identify type, write plan with WHAT/HOW separation)
→ Phase 1c.5: Online Verification → `*** HARD GATE: must print Research Decision block ***`
→ 1c.5+: Dependency Freshness Check (always, if story touches external deps)
→ Phase 1d.7: Story Refinement & Forward Context (gap analysis, cross-story notes)
→ Phase 1f: Clarification Check (ambiguity_scan across 7 categories)
→ Phase 1g: Plan Completeness (verify spec/implementation sections)
→ [User approved?] → NO: Revise → YES: Continue
→ Phase 2: Context Transition + Confidence Gate
→ (prune context, score 5 dimensions, ≥85 proceed, 70-84 clarify, <70 return to Phase 1)
→ Phase 3: Execute by Story Type
→ `*** HARD GATE: TDD ordering — tests BEFORE implementation (Feature/Bug Fix/Refactoring) ***`
→ Web-Assisted Error Recovery (on build/test failure involving external libraries)
→ Bug Fix Web Research (always for bug fix stories — search error patterns first)
→ Phase 4: Verify + Wrap Up
→ Self-review + disaster prevention + ground rules re-check
→ Quality agents dispatched per risk level
→ Security web verification (security-scoped stories — CWE + CVE check)
→ Quality gates `*** HARD GATE: all configured gates must pass ***`
→ UAT generation + sense check (optional — Feature/Bug Fix only)
→ Completion verification (evidence for every AC)
→ Docs + commit
→ [All criteria met?] → NO: Fix + re-verify (max 2 passes) → YES: Report → DONE
Read the **Profile:** line from CLAUDE.md to determine the active project profile.
Skip these phases/steps entirely:
/quality-check with no flags (lean defaults = code only)Keep these (non-negotiable):
Plan is optional for SMALL stories — if the task is clear, go directly to Phase 3 (Build). Safety is unchanged in Lean mode: TDD enforcement, test-before-ship, all hooks active. Lean is less ceremony, not less safe.
Additions beyond standard behavior:
/quality-check --all for EVERY story regardless of risk level (all 5 agents + integration-tester)docs/sessions/.audit-log.jsonl:
{"type":"audit","story":"<id>","story_type":"<type>","profile":"strict","files_changed":["<paths>"],"agents_run":["<names>"],"gates_passed":true,"coverage_delta":"+N%","ts":"<ISO-8601>"}
For STANDARD stories, consider entering Plan Mode at the start of Phase 0 and remaining in it through Phase 2 (Context Transition). This prevents accidental implementation during the planning phases and provides a natural approval checkpoint.
When to use: Complex stories, high-risk changes, or when the user requests careful planning.
How: Enter Plan Mode before Phase 0. The existing Phase 1 already operates in Plan Mode. Exit Plan Mode after plan approval — just before Phase 2 (Context Transition + Confidence Gate) and Phase 3 (Execution).
CRITICAL — After ExitPlanMode: Plan Mode exit wipes the story-cycle skill from context. After ExitPlanMode, you MUST immediately:
remaining_steps list — it is your execution checklistRun the context-prime micro-component from .claude/prompts/context-prime.md to load project context (intent-aware ordering based on the story description).
If $ARGUMENTS matches a story ID pattern (e.g., PROJ-001, S01, E01-S03), search docs/reference/backlog/E*.md for the story:
- [ ] ID — Title (Priority, Status)### ID: Title with inline metadataDefinition of Ready check: If the story has status: draft or is missing verification commands, affected files, or out-of-scope section, warn the user:
"This story doesn't meet the Definition of Ready. Missing: [list]. Consider running
/ideateto refine it, or proceed with caution."
Dependency check: If the story has dependencies listed, verify each dependency story has status done in its epic file. If any dependency is not done, warn:
"Dependency [ID] is not complete (status: [status]). This story may be blocked."
Status update: Set the story's status to in-progress in the epic file (both checklist and detail section). Emit a story lifecycle event:
echo "{\"type\":\"story\",\"event\":\"status-change\",\"id\":\"<story-id>\",\"from\":\"<previous>\",\"to\":\"in-progress\",\"story_type\":\"<type>\",\"size\":\"<size>\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl
If on a sprint branch (branch name matches sprint-*), load the sprint spec for decision context:
docs/sprints/sprint-<number>.md (derive number from branch name)Sprint-aware risk modifier: If the sprint goal explicitly relates to this story's domain (e.g., sprint goal is "auth integration" and story is about auth), note "sprint-aligned" — this story is goal-critical and deserves full depth. If the story is peripheral to the sprint goal (e.g., sprint goal is "auth integration" but story is "update error messages"), note "sprint-peripheral" — keep scope minimal.
Capacity check: If remaining stories (🔲 + 🔄) require more sessions than remain in sprint capacity:
"⚠️ Sprint capacity at risk — [N] stories remaining ([M] sessions needed), [K] sessions available. Consider carrying over the lowest-priority ⏭️ story."
M/L story session guidance: If this story is sized M or L, suggest the three-session pattern:
"This is a [M/L] story (~[2-3/3-5] sessions). Consider: Session 1 = Phase 0-1 (plan + approve), Session 2 = Phase 3 (implement), Session 3 = Phase 4 (verify + commit). Use
/handoffat natural break points to preserve context."
This is guidance, not enforcement — the developer may complete it in fewer sessions.
If docs/reference/PRD_SUMMARY.md exists, load Section 7 (scope boundaries) and Section 3 (success criteria). Use scope boundaries as guard rails throughout implementation — if the story drifts toward a stated non-goal or violates an implementation boundary, flag it. Use success criteria to verify the story contributes to measurable product outcomes.
Before any exploration, decompose the user's request. Apply the scope_analysis reasoning tool from references/reasoning-tools.md:
This prevents missing later parts of compound requests (e.g., "refactor auth AND add rate limiting AND create a PR").
After Phase 0 decomposition, classify by size then risk:
Size classification — use the story's frontmatter size field as starting point (if the story came from the backlog via /ideate). Validate against actual scope after decomposition — reclassify if the scope doesn't match:
| Size | Criteria | Default Workflow |
|---|---|---|
| TRIVIAL | Single file, <10 lines changed, no behavioral change (typo, config, comment) | Phase 3-lite (below) |
| SMALL | One clear change following an existing pattern | Lightweight Phase 1 (skip 1f, 1g) → Phase 2 → Phase 3 → Phase 4 |
| STANDARD | One coherent feature, requires a plan | Full workflow (unchanged) |
| LARGE | One coherent mechanism whose parts interlock and cannot be meaningfully tested in isolation | Full workflow + integration test pass before Phase 4 |
| XL | A complete subsystem with a single conceptual center | Full workflow, staged implementation — build and verify one part of the mechanism at a time, then a full-suite pass before Phase 4 |
Sizing is by conceptual cohesion, not file count — see ../ideate/references/story-template.md.
Do not reclassify a LARGE or XL story downward, or split it, merely because it touches many files.
Split only when it spans genuinely unrelated topics.
Adaptive calibration: If docs/sessions/.activity-log.jsonl contains 10+ skill execution records, check historical data for this story type/scope:
Depth calibration: [escalated/standard/downgraded] based on [N] prior executionsSprint context modifier (from Phase 0a.5): If sprint context was loaded, apply:
Sprint alignment: [aligned/peripheral] — sprint goal: "[goal]"Risk classification (apply risk_classification reasoning tool from references/reasoning-tools.md):
Score domain risk, integration surface, and reversibility (1-3 each). Sum determines risk level:
| Low risk (3-4) | Medium risk (5-6) | High risk (7-9) | |
|---|---|---|---|
| TRIVIAL | Phase 3-lite | Phase 3-lite + full test suite | Reclassify as SMALL |
| SMALL | Lightweight Phase 1 | Standard workflow | Standard + mandatory security-audit |
| STANDARD | Standard workflow | Standard + all quality agents | Standard + all agents + architecture-check |
| LARGE | Standard + integration tests | Standard + all quality agents + integration tests | Standard + all agents + architecture-check + security-audit |
| XL | Staged build + all quality agents | Staged build + all agents + architecture-check | Staged build + all agents + architecture-check + security-audit + integration-tester |
SMALL stories skip Phase 1f (clarification check) and 1g (plan completeness) only. All other phases are REQUIRED — do NOT skip them because the story feels simple:
*** HARD GATE: user approval ****** HARD GATE ****** HARD GATE ***Why this matters: Testing proved that SMALL stories get their quality gates skipped when the agent optimizes for speed. The code may be fine, but the process guarantees are missing. Every gate exists for a reason.
Enter plan mode to research and design the approach.
Pre-flight: Run the discover-commands micro-component from .claude/prompts/discover-commands.md to extract configured commands (test, lint, format, build, typecheck) from CLAUDE.md. Run the verify-clean-git-state micro-component from .claude/prompts/verify-clean-git-state.md to confirm no uncommitted changes and correct branch.
Determine the story type from the description, backlog entry, or user input:
| Type | Indicators | Approach |
|---|---|---|
| Feature | New user-facing capability, "As a user..." | TDD: RED-GREEN-REFACTOR |
| Bug Fix | Defect, "fix", error report, reproduction steps | Reproduce → Test → Fix → Verify |
| Refactoring | "Refactor", "restructure", no behavior change | Characterization tests → Refactor → Verify |
| Spike/Research | "Investigate", "evaluate", "prototype", time-boxed | Explore → Document → Decide |
| Infrastructure | CI/CD, tooling, build, config, environment | Plan → Implement → Smoke Test |
| Testing | "Add tests", "coverage", "E2E tests" | Design strategy → Generate → Validate |
| Documentation | "Document", "write docs", "update README" | Gather → Generate → Review |
| Security | "Harden", "audit", "vulnerability", "encrypt" | Threat model → Implement → Audit |
| Performance | "Optimize", "benchmark", "speed up", "latency" | Baseline → Optimize → Benchmark |
| Skill/Tooling | "Create skill", "add tool", "developer experience" | Design → Build → Document |
| Review | Phase transition, walkthrough, assumption validation, direction decision | Interactive walkthrough → Document findings → Decide direction |
If the story type is ambiguous after checking indicators, ask the user using AskUserQuestion with description fields explaining workflow implications:
Use the grep-first-explore micro-component from .claude/prompts/grep-first-explore.md to efficiently identify relevant files before reading them. The number of exploration streams scales with story size:
| Size | Exploration Strategy |
|---|---|
| TRIVIAL | Skip Phase 1b entirely (already fast-tracked) |
| SMALL | Single grep-first pass: extract terms from the story, run parallel Grep calls, read top 5-7 files |
| STANDARD | Grep-first pass + 1-2 codebase-explorer agents for broader context (architecture focus, test focus) |
| STANDARD + High-risk | Grep-first pass + 2 agents + security-focused grep (search for auth patterns, input validation, trust boundaries in affected modules) |
Grep-first process:
If sub-agents are available (STANDARD stories): Use the wave-execution micro-component from .claude/prompts/wave-execution.md to dispatch codebase-explorer agents in parallel with focused prompts:
Prior learnings check: Search docs/solutions/ for prior learnings on affected modules. Grep frontmatter fields (tags, module, component) for terms from the story. Read matching solution documents to avoid rediscovering known patterns or gotchas.
Collect all results. Deduplicate and synthesize into a focused file list (10-15 files max). Read ONLY the files identified. If during implementation you need additional files, read them then — don't front-load.
If sub-agents are NOT available: Use grep-first only — it's efficient enough for most stories without agent support.
Architecture rules check: If docs/architecture/ARCHITECTURE.md exists and is non-template, read ONLY the Module Map (Dependency Rules subsection) and Known Landmines sections. For each module this story touches, note any applicable rules or landmines in the exploration summary. This avoids wrong-direction implementations and repeat mistakes.
Debt register cross-reference (skip for TRIVIAL stories): If docs/technical-debt.md has active items, grep its Location fields for files identified in exploration. If any explored files appear in active debt items:
docs/context/system-patterns.md exists and is populated (not template-only), check it against the files being touched:
CLAUDE.md files in the target directory and parent directories — these contain module-specific patterns and conventions that supplement global CLAUDE.mdStep 1 — Classify research requirement:
| Story type | Research requirement | Depth |
|---|---|---|
| Spike/Research | MANDATORY | DEEP |
| Security | MANDATORY | STANDARD |
| Bug Fix | MANDATORY (error pattern search) | QUICK |
| All other types | Conditional (evaluate 3 signals below) | Auto-select |
Step 2 — For conditional stories, evaluate these three signals:
| Signal | Research needed | Skip research |
|---|---|---|
| Risk level | High-risk topics: security, payments, auth, external APIs, new dependencies | Low-risk internal changes |
| Local context strength | Weak: unfamiliar library, no existing patterns, no prior solutions in docs/solutions/ | Strong: established patterns, existing tests, prior solution docs cover this area |
| Uncertainty level | Approach is unclear, multiple valid strategies exist | Approach is obvious from codebase conventions |
Decision: If ANY signal points to "research needed" → proceed. Otherwise → skip with justification.
Step 3 — Execute research (when proceeding):
Compose the deep-research methodology (.claude/prompts/deep-research.md) at the depth from Step 1:
| Story context | Research depth |
|---|---|
| Spike/Research | DEEP |
| Security, new external dependencies | STANDARD |
| Bug fix, standard story with research signals | QUICK |
The research engine handles: query decomposition, parallel subagent dispatch, source evaluation, reflection-based compression. See .claude/prompts/deep-research.md.
For Spike/Research stories specifically: Generate sub-questions from the spike's questions. Research current state of reference technologies, recent publications, competitor approaches, and relevant patterns. All claims MUST cite sources with URLs. Training data alone is NEVER sufficient for spikes.
Step 4 — Print the Research Decision block (MANDATORY):
## Research Decision
**Story type:** [type from 1a]
**Research requirement:** [MANDATORY / Conditional]
**Decision:** [PERFORMED at [depth] / SKIPPED]
**Justification:** [why — for skips: which signals were evaluated and why all pointed to skip]
### Findings (if research was performed)
- [Key finding 1 with source URL]
- [Key finding 2 with source URL]
- [Finding N...]
**Research confidence:** [high/medium/low]
**Impact on plan:** [how findings affect the approach — or "No findings that change approach"]
This block is included in the plan and feeds into Phase 2b readiness checks.
Record findings:
Trigger: The story creates, modifies, or directly calls any external dependency (not internal modules). This runs even when the main 1c.5 research gate was skipped.
Quick check (~30 seconds):
WebSearch for: "<library> <pinned-version> deprecation OR breaking change OR CVE" (batch into 1-2 searches)WebFetch the specific page to confirmOutcomes:
| Finding | Action |
|---|---|
| No issues | Note "Dep freshness: all clear" in plan, move on |
| Deprecation notice | Note in plan, use recommended replacement API |
| Known CVE | Flag to user immediately — may change story scope |
| Breaking change in newer version | Note in plan for awareness; no action if pinned version is stable |
Skip when: Story only touches internal code with no external library calls.
Determine which skills benefit this story. If the story metadata already defines skills, use those. Otherwise select from:
| Skill | Load When |
|---|---|
/code-quality | Feature, refactoring, infrastructure stories |
/test-validator | Feature, bug fix, refactoring, testing stories |
/security-audit | Security stories, code touching auth/credentials/data |
Intent-based security activation: If the story touches user input, API endpoints, database queries, file uploads, sessions, or network calls, treat the security rule as active for ALL files in this story — not just files matching security path patterns. Note this in the plan: Security scope: story-wide (intent-based).
Before writing the plan, check: do you have enough information to write a plan without assumptions?
Red flag: If you're about to write "Assuming X..." in the plan, STOP — ask the user about X instead. Facilitate discovery; don't generate assumptions.
With codebase understanding from 1b-1c, pressure-test the story before planning:
> Context from [this story]: ... note to those stories in the epic file.Summarize: what was refined, what gaps were found, what forward context was added.
Keep the plan concise — under 50 lines. Save complex plans to docs/plans/ for persistence across compaction. Reference files by path rather than inlining content.
Follow the plan template structure in references/plan-template.md. The plan MUST have two distinct sections:
For any requirement where the user's intent is ambiguous or multiple valid interpretations exist, insert [NEEDS CLARIFICATION: specific question] in the plan. Maximum 3 markers before triggering a hard gate for user input.
Apply the test_strategy_selection reasoning tool for the testing section.
Apply the ambiguity_scan reasoning tool from references/reasoning-tools.md. Scan the plan for assumptions across 7 categories (scope, data model, UX, non-functional, integration, edge cases, constraints).
Apply the plan_completeness reasoning tool from references/reasoning-tools.md to verify:
CRITICAL — Story-Cycle Context Preservation:
After plan approval, context resets and only the plan survives. The plan MUST start with a "Story-Cycle Context" section so Claude Code knows what workflow it's in and what steps remain. Update the phase and stepsCompleted fields at each phase transition — this enables true mid-workflow resume if the session is interrupted or context compacts.
Use this exact format at the TOP of the plan:
## Story-Cycle Context
workflow: story-cycle
storyType: "[from Phase 1a]"
sprint_number: [N]
sprint_goal: "[from Phase 0a.5 — one sentence]"
sprint_alignment: "[aligned/peripheral — from Size & Risk Classification]"
phase: "plan-approved — proceed to Phase 2 Context Transition + Confidence Gate"
stepsCompleted: [0-intent, 0a5-sprint-context, 1a-type, 1b-discovery, 1c-research, 1c5-online-verify, 1d-skills, 1d5-discovery-gate, 1d7-refinement, 1e-plan, 1f-clarification, 1g-completeness, 1h-depth-check]
remaining_steps:
- "BOOTSTRAP (do this FIRST): Read .claude/skills/story-cycle/SKILL.md starting from '## Phase 2: Context Transition + Confidence Gate' to reload the full story-cycle workflow. You are mid-workflow — planning is done, implementation phases remain. Do NOT stop after reading the plan."
- "Phase 2 — CONTEXT + READINESS GATE (HARD-GATE): Prune context (keep plan + paths + gotchas, discard bulk). Read .claude/prompts/confidence-gate.md. Verify 5 objective checks (files read, tests baseline, pattern match, scope bounded, no conflicts). All pass → proceed. Any fail → address gap. Output the check results."
- "Phase 3 — IMPLEMENT (TDD HARD-GATE for Feature/Bug Fix/Refactoring): Read .claude/skills/story-cycle/references/story-types.md for [storyType] execution steps. Load relevant sections of docs/reference/CODING_STANDARDS.md and docs/reference/TESTING_STRATEGY.md. Re-read all target files from plan before editing. CRITICAL: For Feature/Bug Fix/Refactoring stories, write and run a failing test BEFORE writing implementation code. Show test failure output. Only then write implementation. Follow story-type methodology (TDD: RED → GREEN → REFACTOR)."
- "Phase 4a — SELF-REVIEW (HARD-GATE): Read .claude/skills/story-cycle/references/self-review.md — complete ALL checklist items including ground rules re-check. Read .claude/skills/story-cycle/references/disaster-prevention.md — check for wheel reinvention, spec drift, integration wiring, file structure, regression surface, architecture doc staleness. Dispatch quality skills per risk level (Low: code-quality+test-validator+security-audit-lightweight, Medium: +security-audit-full, High: +architecture-check). At Medium+ risk, also dispatch integration-tester native agent (.claude/agents/integration-tester.md) with test commands + acceptance criteria for independent dynamic verification. If ANY item fails → fix in Phase 3 before proceeding."
- "Phase 4b — QUALITY GATES (HARD-GATE): Run the project's quality command (from CLAUDE.md Commands section: lint → typecheck → test). Stop on first failure, fix, re-run. Show passing output in the current turn — do NOT claim tests pass without evidence. Do NOT proceed until all gates pass."
- "Phase 4b.5 — LAUNCH & VERIFY (optional, Feature/Bug Fix only): Check CLAUDE.md Commands for a dev command. If one exists AND the story type is Feature or Bug Fix: offer to run it so the user can visually verify. Run in background, show whatever output it produces (URLs, status, CLI output — do NOT assume localhost). Ask: 'Want to verify it visually?' If user declines or no dev command exists, skip. Also skip for Spike, Infrastructure, Documentation, Testing, Refactoring, Performance, Skill/Tooling, Review stories."
- "Phase 4c — UAT (optional, Feature/Bug Fix only): If project has UAT directory, generate UAT test case + sense check per Phase 4c/4c.1 in SKILL.md. Skip for Spike/Research, Infrastructure, Documentation, Testing, Refactoring, Performance, Skill/Tooling stories. Also skip if no UAT directory exists."
- "Phase 4d — COMPLETION VERIFICATION (HARD-GATE): Re-read original AC from plan. For EACH criterion, provide concrete evidence (test output, file:line, command output). Max 2 extra loop passes if gaps found. Do NOT print completion report until every AC has evidence."
- "Phase 4e — DOCS + COMMIT: (1) Update epic file (mark story DONE in heading, check all AC boxes). (2) Update BACKLOG_INDEX.md (increment Done, decrement TODO for epic row, update Total row). (3) Update docs/progress.md (story status ✅). (4) Update sprint spec (docs/sprints/sprint-N.md): set story Status to ✅, Session column to today's date. (5) Update CLAUDE.md if it contains backlog counts or epic progress that changed. (6) Emit skill metrics event to docs/sessions/.activity-log.jsonl. (7) Invoke /commit skill. Do NOT merge or create PR — that is sprint-end."
- "COMPLETION REPORT: Print story, type, approach, files modified, test counts, commit hash, verification evidence. Include Next Steps section with concrete commands. Determine the next story from the sprint spec (docs/sprints/sprint-N.md) or epic file — find the first story with status TODO/ready. Format: '**Next steps:**\n1. Clear your context window: `/clear`\n2. Start the next story: `/story-cycle [next-story-id]`' — always use the actual story ID. If no stories remain, suggest `/sprint-end` instead."
error_recovery: ".claude/skills/story-cycle/references/error-recovery.md"
skill_file: ".claude/skills/story-cycle/SKILL.md"
<files-read>
[List all files read during planning — one path per line]
</files-read>
<files-modified>
[Update as files are modified during execution — one path per line]
</files-modified>
When context compacts, MERGE new file paths into these lists — never discard previous entries.
When you exit Plan Mode (ExitPlanMode) during a story-cycle, you are NOT done. Planning is only Phase 1 of 4. After Plan Mode exits, you MUST:
.claude/skills/story-cycle/SKILL.md starting from ## Phase 2: Context Transition + Confidence Gateremaining_steps from the plan's Story-Cycle Context block IN ORDERThe plan approval is a checkpoint, not the finish line. If you stop after Plan Mode, the story is incomplete — no code was written, no tests were run, nothing was committed.
For complex stories, use ultrathink to reason through architectural decisions before writing the plan.
Before presenting for approval, offer the user a depth option if the plan contains areas with complexity ≥4 or unresolved uncertainties:
depth_exploration reasoning tool and elicitation techniques from references/elicitation-techniques.mdIf [D]: apply the most relevant elicitation technique, integrate findings into the plan, then present for approval. If [C] or no uncertainties exist: proceed directly to approval.
Present the plan for user approval.
After plan approval, prune context and score confidence in a single pass.
KEEP: The approved plan (with Story-Cycle Context header), file paths from research, edge cases/gotchas, pattern snippets. DISCARD: Full file contents from exploration, dead-end investigations, irrelevant search results. RELOAD for Phase 3 (section-specific to save context):
docs/reference/CODING_STANDARDS.md — load ONLY the section for the story's language/stack (e.g., ## Python or ## TypeScript), plus the ## Universal Conventions and ## AI-Specific Anti-Patterns sections. Skip other language sections.docs/reference/TESTING_STRATEGY.md — load ONLY the ## Test Infrastructure section (project-specific commands) and the section matching the story type (e.g., ## Feature Story or ## Bug Fix). Skip unrelated story-type sections.docs/progress.md, docs/architecture/ARCHITECTURE.md, backlog files, docs/reference/GROUND_RULES.md (already checked in Phase 1e).Re-read target files before editing — context may have changed since Phase 1.
Run the confidence-gate micro-component from .claude/prompts/confidence-gate.md. Verify 5 objective pre-conditions (files read, tests baseline, pattern match, scope bounded, no conflicts) as PASS or FAIL.
| Result | Action |
|---|---|
| All 5 pass | Proceed to Phase 3 |
| Any fail | Address the specific gap (re-read missing files, run tests, check rules) |
| User override | Proceed with acknowledgment of overridden checks |
The Stop hook auto-saves git state to docs/sessions/.auto-save.md (branch, recent commits, uncommitted files). The /continue skill uses this plus git state to resume interrupted workflows. No manual state file management needed.
Before writing any implementation code, create a checkpoint so the entire implementation can be cleanly rolled back if verification fails:
git tag "story-checkpoint-$(date +%s)" HEAD
Record the tag name in .failure-state.md under a checkpoint_tag field. This tag is used by Phase 4 if verification fails — see "Checkpoint Rollback" in Phase 4d.
On successful story completion (Phase 4e commit), delete the checkpoint tag:
git tag -d "story-checkpoint-*" # Clean up
After each completed TDD cycle (test written → implementation passes → tests green), create an intermediate commit:
git add <changed-files>
git commit -m "<type>(<scope>): <description of this unit>"
These intermediate commits:
For TRIVIAL and SMALL stories, a single commit at Phase 4e is sufficient.
In references/story-types.md, search for the ## [Your Story Type] heading matching Phase 1 — load only that section, not the entire file.
Before writing the first test, apply the test_strategy_selection reasoning tool from references/reasoning-tools.md.
For story types that require tests (Feature, Bug Fix, Refactoring), you MUST write and run test code BEFORE writing implementation code. This is not optional — it is the framework's #1 principle.
Feature stories (RED-GREEN-REFACTOR):
Bug Fix stories:
Refactoring stories:
What "before" means concretely: The first Edit or Write call to a source file (non-test) MUST be preceded by at least one Edit or Write call to a test file, AND a Bash call that ran the test and showed output. If you find yourself about to edit a source file without having written and run a test first, STOP and write the test.
Exceptions: Spike/Research, Infrastructure, Documentation, Testing, Performance, Security, Skill/Tooling stories follow their own methodology from references/story-types.md and are not subject to this gate.
When errors occur during execution, consult references/error-recovery.md — search for ## Phase 3 for the recovery table.
When a build error, test failure, or runtime exception involves an external library (not internal logic), use the research engine before guessing:
Trigger: Error message contains a library name, unfamiliar API, or stack trace pointing outside the project's source tree. Does NOT trigger for purely internal logic errors (wrong variable, missing import of own module, etc.).
Protocol: Compose the deep-research methodology (.claude/prompts/deep-research.md) at QUICK depth:
evidence-check (fix or workaround with source citation)Time budget: Max 60 seconds of web research per error. If nothing useful surfaces, move on — don't spiral.
Bug fix stories — proactive search: For bug fix story types, search the error pattern at the START of Phase 3 (before attempting a fix), not just after failure. The error message is the most valuable search query you have — use it early. See references/story-types.md for the updated Bug Fix workflow.
This phase combines self-review, quality gates, UAT, and completion verification into a single pass. All checks are mandatory — none are skipped because the story feels simple.
Read references/self-review.md and complete the checklist (completeness, quality, testing, discipline).
Then read references/disaster-prevention.md — check for: wheel reinvention, spec drift, integration wiring, file structure, regression surface.
Security web verification (security-scoped stories only): If the story was tagged with intent-based security activation (Phase 1d) or is a Security story type, perform a targeted web check before quality gates. See references/self-review.md → "Security Web Verification" section for the protocol.
Ground rules re-check: If docs/reference/GROUND_RULES.md exists, re-read it and verify the IMPLEMENTATION (not just the plan) complies. Plans can comply while implementation drifts. Check git diff --name-only against ground rules — any MUST violation requires fixing before proceeding.
Persona cross-check (medium+ risk, user-facing stories only): If docs/context/personas.md exists AND the story has a Personas: field (not "internal"), scan the implementation for persona-mismatch issues that functional AC wouldn't catch:
Personas: fieldFocus on surface-level mismatches between implementation and persona constraints — not whether the feature conceptually serves the persona (the AC already covers that).
Skip when: Story is TRIVIAL or low risk (3-4), story has Personas: internal, or personas.md doesn't exist.
If sub-agents are available: Dispatch quality gates via /quality-check based on the risk matrix from Size & Risk Classification:
| Risk Level | /quality-check Invocation | Notes |
|---|---|---|
| Low (3-4) | /quality-check (profile defaults) | Standard: code+tests+security. Lean: code only. |
| Medium (5-6) | /quality-check --code --tests --security | Plus integration-tester at standard+ profiles |
| High (7-9) | /quality-check --all | All 5 agents + integration-tester (mandatory) |
Why security at ALL risk levels: AI-generated code contains vulnerabilities 40-45% of the time regardless of story type. /quality-check handles lightweight vs full security pass based on flags.
Why integration-tester at Medium+ risk: The implementing LLM verifies its own work in Phase 4b (self-assessment). The integration-tester agent independently re-runs the test suite and verifies acceptance criteria — breaking the self-verification cycle. At low risk, Phase 4b's quality-gate-sequence is sufficient.
If sub-agents are NOT available: Complete self-review checklist manually. Do NOT skip quality checks.
Error learning: If self-review caught a wrong approach requiring significant rework, invoke the record-failure micro-component from .claude/prompts/record-failure.md.
Run the quality-gate-sequence micro-component from .claude/prompts/quality-gate-sequence.md: execute the project's quality commands (from CLAUDE.md Commands section) in order: lint → typecheck → test. Stop on first failure, fix, and re-run.
Applies to: Feature and Bug Fix stories that affect user-visible behavior, AND the project has UAT tracking (docs/testing/UAT_COVERAGE.md, docs/testing/uat/, or tests/uat/).
Skip for: Spike/Research, Infrastructure, Documentation, Testing, Refactoring, Performance, Skill/Tooling stories. Also skip if no UAT file or directory exists in the project.
docs/testing/UAT_COVERAGE.md (single-file), docs/testing/uat/ (directory), or tests/uat/scenarios/. If none exists, skip this phase entirely.### UAT- headings in existing files, increment the highest number, format as UAT-### (zero-padded to 3 digits).### UAT-NNN: [Title derived from story]**Priority:** [risk-based] | **Type:** [positive|negative|boundary] | **Covers:** [Story IDs] | **Tags:** [relevant tags]**Setup:** — preconditions from story context**Given** / **When** / **Then** / **And** — one per acceptance criterion; create multiple test cases if an AC needs multiple scenarios**Test Data:** table if applicable**Status:** ⬜ Untested / **Tested On:** — / **Findings:** —**Claude Sense Check** and **Human UAT Check** checkbox sections#### Results append-only table with initial ⬜ Untested rowdocs/testing/UAT_COVERAGE.md): Append before the ## Reference sectiondocs/testing/uat/ or tests/uat/): Create a new file following existing naming conventionApplies when: A UAT test case was generated in Phase 4c. Skip when: No UAT case was generated.
Since the implementation code is fresh in context, immediately verify the UAT case logic:
- [x] Logic verified from code perspectiveRe-read the original acceptance criteria from the plan. For each criterion, provide concrete evidence: test output, code reference (file:line), or command output.
Checkpoint Rollback Option: If verification has failed after 2 loop passes and the implementation appears fundamentally flawed (not just minor gaps), offer the user a rollback:
Verification failed after 2 passes. Options:
[R] Rollback — restore to pre-implementation checkpoint (git tag from Phase 3.pre) and re-plan
[C] Continue — keep current code and address remaining gaps in next session
[F] Force complete — mark as done with known gaps documented
If [R]: git stash push --include-untracked -m "story-cycle: checkpoint rollback" && git reset --soft <checkpoint-tag> && git restore . && git tag -d <checkpoint-tag>. Clear .failure-state.md. Suggest re-entering Phase 1 with lessons learned.
If [C]: Save state to .failure-state.md for /continue pickup.
If [F]: Document gaps in completion report, proceed to Phase 4e.
capture-outcome micro-component from .claude/prompts/capture-outcome.md to record measurable deltas (lines added/removed, test count, coverage, new deps) to docs/sessions/.story-outcomes.tsv. Skip for Spike/Research and Documentation stories.docs/reference/backlog/E##-*.md):
- [ ] ID — Title (P#, in-progress) → - [ ] ID — Title (P#, review)**Status:** review[DONE] if epic uses old markers- [ ] → - [x])echo "{\"type\":\"story\",\"event\":\"status-change\",\"id\":\"<id>\",\"from\":\"in-progress\",\"to\":\"review\",\"story_type\":\"<type>\",\"size\":\"<size>\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl
docs/reference/BACKLOG_INDEX.md: Update story counts per priority group in the status table.docs/progress.md with story status (✅)
4.5. Update sprint spec (docs/sprints/sprint-<N>.md): set this story's Status to ✅ and Session column to today's date (YYYY-MM-DD). This creates the session-to-sprint mapping needed for cycle time calculation and retrospective analysis.docs/architecture/ARCHITECTURE.md. If ANY trigger matches changes in this story (git diff --name-only), update the relevant sections and set Last Verified date to today. Also:
capture-learnings micro-component from .claude/prompts/capture-learnings.md to save to docs/solutions/<topic-slug>.mdgit tag -l 'story-checkpoint-*' | xargs -r git tag -d/commit skill. Do NOT merge or create PR — that's /sprint-end's job.Skill metrics: Emit a completion event:
echo "{\"type\":\"skill\",\"event\":\"end\",\"skill\":\"story-cycle\",\"outcome\":\"success\",\"story\":\"$ARGUMENTS\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl
### Story Complete
**Story:** [description]
**Type:** [story type]
**Approach:** [methodology used]
**Files modified:** [list]
**Tests:** [count] passing, [new tests added]
**Commit:** [hash and message]
**Verification:** [All N acceptance criteria verified — see evidence above]
**Next Steps:**
→ `/story-cycle "[next story from backlog]"` — deliver the next story
→ `/sprint-end` — if this was the last story in the sprint
→ `/handoff` — if ending the session
For phase-specific error recovery, consult references/error-recovery.md — search for the relevant ## Phase N section.
General recovery:
docs/technical-debt.md if out of scope.docs/plans/, commit work-in-progress, inform user to start a new session with /continue./code-quality) is not available, skip it and note in the completion report.docs/reference/CODING_STANDARDS.mddocs/reference/TESTING_STRATEGY.mddocs/architecture/ARCHITECTURE.mddocs/reference/GROUND_RULES.md (if exists)