agentleFS
joris887joris887/exosuit/.claude/skills/story-cycle/SKILL.md

story-cycle

Skill9 starsChanged 3 months agoMITView on GitHub

Use when the user wants to implement a single story or deliver a backlog item.

The file

Show its rules and text

We split this skill into the rules it gives an agent

124 rules. About 0 are common, 79 are distinctive, and 45 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈79

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 45

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Read the Profile: line from CLAUDE.md to determine the active project profile.

    line 76
  2. Distinctive:

    All 8 phases are mandatory for ALL stories including TRIVIAL — no fast-tracking, no Phase 3-lite

    line 105
  3. Very specific:

    Read the plan file's remaining_steps list — it is your execution checklist

    line 125
  4. Very specific:

    Run the context-prime micro-component from .claude/prompts/context-prime.md to load project context (intent-aware ordering based on the …

    line 131
  5. Very specific:

    If $ARGUMENTS matches a story ID pattern (e.g., PROJ-001, S01, E01-S03), search docs/reference/backlog/E*.md for the story:

    line 135
  6. Very specific:

    Use extracted type/size/priority as starting classification (validated in the Size & Risk Classification step)

    line 140
  7. Very specific:

    Definition of Ready check: If the story has status: draft or is missing verification commands, affected files, or out-of-scope section, …

    line 142
  8. Very specific:

    Dependency check: If the story has dependencies listed, verify each dependency story has status done in its epic file.

    line 145
  9. Very specific:

    If on a sprint branch (branch name matches sprint-*), load the sprint spec for decision context:

    line 155
  10. Distinctive:

    Capacity check: If remaining stories (🔲 + 🔄) require more sessions than remain in sprint capacity:

    line 166
  11. Distinctive:

    M/L story session guidance: If this story is sized M or L, suggest the three-session pattern:

    line 169
  12. Distinctive:

    Do NOT re-decide settled questions.

    line 184
  13. Distinctive:

    If implementation reveals an assumption is wrong, update the register: set status → INVALIDATED, add evidence in the Evidence column.

    line 189
  14. Very specific:

    Before any exploration, decompose the user's request.

    line 200
  15. Distinctive:

    If the request contains multiple independent stories, suggest splitting and confirm scope

    line 205
  16. Distinctive:

    After Phase 0 decomposition, classify by size then risk:

    line 212
  17. Distinctive:

    Do not reclassify a LARGE or XL story downward, or split it, merely because it touches many files.

    line 225
  18. Very specific:

    Adaptive calibration: If docs/sessions/.activity-log.jsonl contains 10+ skill execution records, check historical data for this story …

    line 228
  19. Distinctive:

    If stories matching this type consistently required full workflow despite SMALL classification → escalate to STANDARD

    line 229
  20. Distinctive:

    If STANDARD stories in this area consistently completed without issues → note as candidate for lightweight treatment

    line 230
  21. Distinctive:

    Red flag: If editing multiple files or changing observable behavior, STOP and reclassify as STANDARD.

    line 251
  22. Distinctive:

    All other phases are REQUIRED — do NOT skip them because the story feels simple:

    line 257
  23. Distinctive:

    Run tests (if test command configured)

    line 270
  24. Distinctive:

    Commit with conventional format

    line 272
  25. Very specific:

    Pre-flight: Run the discover-commands micro-component from .claude/prompts/discover-commands.md to extract configured commands (test, lint, …

    line 279
  26. Very specific:

    If the story type is ambiguous after checking indicators, ask the user using AskUserQuestion with description fields explaining workflow …

    line 299
  27. Very specific:

    Use the grep-first-explore micro-component from .claude/prompts/grep-first-explore.md to efficiently identify relevant files before reading …

    line 314
  28. Distinctive:

    Run parallel Grep calls: imports/usage, definitions, and test references

    line 325
  29. Distinctive:

    If fewer than 3 files match (greenfield or entirely new feature): fall back to codebase-explorer agents

    line 327
  30. Very specific:

    If sub-agents are available (STANDARD stories): Use the wave-execution micro-component from .claude/prompts/wave-execution.md to dispatch …

    line 329
  31. Very specific:

    Prior learnings check: Search docs/solutions/ for prior learnings on affected modules.

    line 333
  32. Distinctive:

    If sub-agents are NOT available: Use grep-first only — it's efficient enough for most stories without agent support.

    line 337
  33. Very specific:

    Architecture rules check: If docs/architecture/ARCHITECTURE.md exists and is non-template, read ONLY the Module Map (Dependency Rules …

    line 339
  34. Very specific:

    Debt register cross-reference (skip for TRIVIAL stories): If docs/technical-debt.md has active items, grep its Location fields for files …

    line 341
  35. Very specific:

    If docs/context/system-patterns.md exists and is populated (not template-only), check it against the files being touched:

    line 349
  36. Distinctive:

    Check for CLAUDE.md files in the target directory and parent directories — these contain module-specific patterns and conventions that …

    line 356
  37. Distinctive:

    Decision: If ANY signal points to "research needed" → proceed.

    line 381
  38. Distinctive:

    If official docs reveal a deprecation or API change: note it in the plan as a "Doc Finding" and update relevant reference docs after …

    line 420
  39. Distinctive:

    If a better approach is found: incorporate it into the plan

    line 421
  40. Distinctive:

    If everything checks out: note "Online verification: APIs confirmed current" and move on

    line 422
  41. Very specific:

    If a result looks relevant, WebFetch the specific page to confirm

    line 432
  42. Distinctive:

    Intent-based security activation: If the story touches user input, API endpoints, database queries, file uploads, sessions, or network …

    line 455
  43. Distinctive:

    Before writing the plan, check: do you have enough information to write a plan without assumptions?

    line 459
  44. Distinctive:

    If YES: proceed to 1d.7

    line 461
  45. Distinctive:

    If NO: present the 3 most critical unknowns to the user as focused questions with 2-4 answer options each.

    line 462
  46. Distinctive:

    Red flag: If you're about to write "Assuming X..." in the plan, STOP — ask the user about X instead.

    line 464
  47. Very specific:

    Keep the plan concise — under 50 lines.

    line 480
  48. Very specific:

    Follow the plan template structure in references/plan-template.md.

    line 482
  49. Very specific:

    Check the plan against docs/reference/GROUND_RULES.md.

    line 496
  50. Distinctive:

    All deliverables from Phase 0 have implementation steps

    line 510
  51. Distinctive:

    All acceptance criteria have verification approaches

    line 511
  52. Distinctive:

    Use this exact format at the TOP of the plan:

    line 520
  53. Distinctive:

    When context compacts, MERGE new file paths into these lists — never discard previous entries.

    line 558
  54. Distinctive:

    When you exit Plan Mode (ExitPlanMode) during a story-cycle, you are NOT done.

    line 563
  55. Very specific:

    Read .claude/skills/story-cycle/SKILL.md starting from ## Phase 2: Context Transition + Confidence Gate

    line 566
  56. Distinctive:

    Do NOT report completion until Phase 4d passes with evidence for every acceptance criterion

    line 568
  57. Distinctive:

    Before presenting for approval, offer the user a depth option if the plan contains areas with complexity ≥4 or unresolved uncertainties:

    line 578
  58. Distinctive:

    If [D]: apply the most relevant elicitation technique, integrate findings into the plan, then present for approval.

    line 583
  59. Distinctive:

    If [C] or no uncertainties exist: proceed directly to approval.

    line 584
  60. Distinctive:

    Do NOT write any implementation code, edit source files, or take any implementation action until the plan has been presented and the user …

    line 589
  61. Distinctive:

    After plan approval, prune context and score confidence in a single pass.

    line 594
  62. Very specific:

    Run the confidence-gate micro-component from .claude/prompts/confidence-gate.md.

    line 610
  63. Distinctive:

    Do NOT skip the readiness gate for ANY story size except TRIVIAL.

    line 619
  64. Distinctive:

    Check for file overlaps — if ANY file appears in multiple streams, merge those streams

    line 628
  65. Distinctive:

    If ≥2 non-overlapping streams exist, present the stream analysis to the user

    line 629
  66. Distinctive:

    If user approves: create worktrees per stream, dispatch agents, coordinate merges

    line 630
  67. Distinctive:

    If user declines or streams overlap: proceed to serial Phase 3 </IF> <ELSE> Skip — proceed directly to Phase 3.

    line 631
  68. Distinctive:

    Before writing any implementation code, create a checkpoint so the entire implementation can be cleanly rolled back if verification fails:

    line 645
  69. Distinctive:

    After each completed TDD cycle (test written → implementation passes → tests green), create an intermediate commit:

    line 660
  70. Distinctive:

    Prevent data loss: if the session crashes mid-implementation

    line 668
  71. Distinctive:

    Should each leave the codebase in a working state (tests pass)

    line 671
  72. Very specific:

    Before writing the first test, apply the test_strategy_selection reasoning tool from references/reasoning-tools.md.

    line 677
  73. Distinctive:

    Write a failing test for the first behavior (RED) — run it, show the failure output

    line 685
  74. Distinctive:

    Only THEN write the minimum implementation to make it pass (GREEN)

    line 686
  75. Distinctive:

    Write a reproduction test that captures the bug (must FAIL) — run it, show the failure output

    line 691
  76. Distinctive:

    Only THEN implement the fix

    line 692
  77. Distinctive:

    Verify the reproduction test now passes

    line 693
  78. Distinctive:

    Write characterization tests that capture current behavior (must PASS) — run them, show the output

    line 696
  79. Distinctive:

    Only THEN perform the refactoring

    line 697
  80. Distinctive:

    Verify characterization tests still pass after each step

    line 698
  81. Very specific:

    When errors occur during execution, consult references/error-recovery.md — search for ## Phase 3 for the recovery table.

    line 705
  82. Distinctive:

    When a build error, test failure, or runtime exception involves an external library (not internal logic), use the research engine before …

    line 709
  83. Very specific:

    Read references/self-review.md and complete the checklist (completeness, quality, testing, discipline).

    line 731
  84. Distinctive:

    Security web verification (security-scoped stories only): If the story was tagged with intent-based security activation (Phase 1d) or is a …

    line 735
  85. Distinctive:

    Do NOT skip self-review for ANY story size.

    line 738
  86. Very specific:

    Ground rules re-check: If docs/reference/GROUND_RULES.md exists, re-read it and verify the IMPLEMENTATION (not just the plan) complies.

    line 741
  87. Distinctive:

    Check user-facing text: Do error messages, labels, or instructions use jargon that conflicts with the persona's CONTEXT (tech proficiency)?

    line 746
  88. Distinctive:

    Check interaction patterns: Does the UI/UX match the persona's BEHAVIORS (e.g., keyboard navigation for accessibility, mobile-first for …

    line 747
  89. Distinctive:

    Check the persona's FAILURE LOOKS LIKE scenarios: Is any of them possible in this implementation?

    line 748
  90. Very specific:

    Error learning: If self-review caught a wrong approach requiring significant rework, invoke the record-failure micro-component from …

    line 776
  91. Very specific:

    Run the quality-gate-sequence micro-component from .claude/prompts/quality-gate-sequence.md: execute the project's quality commands (from …

    line 780
  92. Distinctive:

    Run any configured commands (lint, typecheck).

    line 786
  93. Distinctive:

    Do NOT proceed to Phase 4c/4d until ALL configured quality gates pass with zero failures.

    line 790
  94. Very specific:

    Find UAT location: Check for docs/testing/UAT_COVERAGE.md (single-file), docs/testing/uat/ (directory), or tests/uat/scenarios/.

    line 798
  95. Very specific:

    Find next UAT ID: Search for ### UAT- headings in existing files, increment the highest number, format as UAT-### (zero-padded to 3 digits).

    line 799
  96. Distinctive:

    Skip when: No UAT case was generated.

    line 817
  97. Very specific:

    Check the box: - [x] Logic verified from code perspective

    line 833
  98. Distinctive:

    If any criterion lacks evidence: identify the gap, loop back to Phase 3 for that specific item, re-verify.

    line 841
  99. Distinctive:

    Checkpoint Rollback Option: If verification has failed after 2 loop passes and the implementation appears fundamentally flawed (not just …

    line 847
  100. Very specific:

    If [R]: git stash push --include-untracked -m "story-cycle: checkpoint rollback" && git reset --soft <checkpoint-tag> && git restore .

    line 856
  101. Very specific:

    If [C]: Save state to .failure-state.md for /continue pickup.

    line 857
  102. Distinctive:

    If [F]: Document gaps in completion report, proceed to Phase 4e.

    line 858
  103. Distinctive:

    Do NOT print the completion report until every acceptance criterion has been verified with evidence.

    line 862
  104. Very specific:

    Capture story outcome: Run the capture-outcome micro-component from .claude/prompts/capture-outcome.md to record measurable deltas (lines …

    line 867
  105. Very specific:

    Check all acceptance criteria boxes in the detail section (- [ ] → - [x])

    line 872
  106. Very specific:

    Update docs/reference/BACKLOG_INDEX.md: Update story counts per priority group in the status table.

    line 877
  107. Distinctive:

    Update documentation: only if the story's AC requires it

    line 880
  108. Very specific:

    Architecture documentation check: Read the Update Triggers section of docs/architecture/ARCHITECTURE.md.

    line 881
  109. Distinctive:

    If a non-obvious gotcha was discovered during implementation → add to Known Landmines

    line 882
  110. Distinctive:

    If a significant architectural choice was made → add to Key Decisions with trade-off

    line 883
  111. Distinctive:

    If no Update Trigger matches, skip

    line 884
  112. Very specific:

    Clean up checkpoint: Delete the git checkpoint tag from Phase 3.pre: git tag -l 'story-checkpoint-*' | xargs -r git tag -d

    line 886
  113. Distinctive:

    Test failure (new code): Read the error, fix the implementation, re-run.

    line 919
  114. Very specific:

    Skill not found: If a required skill (e.g., /code-quality) is not available, skip it and note in the completion report.

    line 923
  115. Distinctive:

    Implementation fundamentally wrong: If Phase 4 reveals the approach is flawed, use the checkpoint rollback option (Phase 4d) to cleanly …

    line 924
  116. Distinctive:

    NEVER skip the plan phase — always enter plan mode first

    line 928
  117. Distinctive:

    NEVER carry exploration context into execution — clear and reload

    line 929
  118. Distinctive:

    NEVER merge to main or create a PR — that's sprint-end

    line 930
  119. Distinctive:

    NEVER add features not in the acceptance criteria

    line 931
  120. Distinctive:

    NEVER weaken or delete existing tests

    line 932
  121. Very specific:

    Follow coding standards in docs/reference/CODING_STANDARDS.md

    line 933
  122. Very specific:

    Follow testing strategy in docs/reference/TESTING_STRATEGY.md

    line 934
  123. Very specific:

    Follow architecture constraints in docs/architecture/ARCHITECTURE.md

    line 935
  124. Very specific:

    Follow project ground rules in docs/reference/GROUND_RULES.md (if exists)

    line 936

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

story-cycle

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:

  1. "Phase 0+1: Decompose intent, research, plan" — activeForm: "Planning..."
  2. "Phase 2: Context transition + readiness gate" — activeForm: "Preparing..." — blockedBy: [1]
  3. "Phase 3: Implement by story type" — activeForm: "Implementing..." — blockedBy: [2]
  4. "Phase 4: Verify, quality gates, commit" — activeForm: "Verifying..." — blockedBy: [3]

At each phase boundary, mark the current task completed and the next task in_progress.

Process Flow (authoritative — prose below is supporting detail)

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

Profile-Adaptive Behavior

Read the **Profile:** line from CLAUDE.md to determine the active project profile.

<IF condition="Profile is lean"> **Lean mode active.** Simplified workflow: Plan (optional for SMALL) -> Build -> Verify.

Skip these phases/steps entirely:

  • Phase 0a.5 (sprint context loading)
  • Phase 1f (clarification check) and Phase 1g (plan completeness check)
  • Phase 2 confidence gate scoring — only run objective pre-checks: are planned files read? do existing tests pass?
  • Phase 4a quality agent dispatch — use /quality-check with no flags (lean defaults = code only)
  • Phase 4c (UAT generation)
  • Phase 4e capture-outcome and capture-learnings micro-components

Keep these (non-negotiable):

  • Phase 0 (intent decomposition and size classification)
  • Phase 1 core (1a-1e for STANDARD stories; skip Phase 1 entirely for SMALL — go directly to Build)
  • Phase 3 (implementation with TDD for Feature/Bug Fix/Refactoring story types)
  • Phase 4b quality-gate-sequence (lint + test from CLAUDE.md Commands)
  • Phase 4d (completion verification — all AC met with evidence)
  • Phase 4e commit and completion report

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. </IF>

<IF condition="Profile is strict"> **Strict mode active.** Maximum rigor for all story sizes.

Additions beyond standard behavior:

  • All 8 phases are mandatory for ALL stories including TRIVIAL — no fast-tracking, no Phase 3-lite
  • Phase 4a: dispatch /quality-check --all for EVERY story regardless of risk level (all 5 agents + integration-tester)
  • Coverage delta must be >= 0 (test coverage cannot decrease). Compare before/after in Phase 4b.
  • Security audit runs full CWE checklist (all 15 entries) for ALL stories, not just security-scoped ones
  • On story completion (Phase 4e), write structured audit entry to 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>"}
</IF>

Plan Mode for Phases 0-2 (Optional)

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:

  1. Read the plan file's remaining_steps list — it is your execution checklist
  2. The first step (BOOTSTRAP) tells you to re-read this skill file from Phase 2 onwards
  3. Continue executing all remaining phases (2 → 3 → 4) — do NOT stop

Phase 0: Intent Decomposition

Run the context-prime micro-component from .claude/prompts/context-prime.md to load project context (intent-aware ordering based on the story description).

0a. Backlog Story Lookup

If $ARGUMENTS matches a story ID pattern (e.g., PROJ-001, S01, E01-S03), search docs/reference/backlog/E*.md for the story:

  1. Find the story in the epic checklist: - [ ] ID — Title (Priority, Status)
  2. Find the detailed story section: ### ID: Title with inline metadata
  3. Extract metadata: Type, Size, Priority, Status, Dependencies, Affected files, Acceptance criteria, Verification commands
  4. Use extracted type/size/priority as starting classification (validated in the Size & Risk Classification step)

Definition 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 /ideate to 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

0a.5. Sprint Context Load

If on a sprint branch (branch name matches sprint-*), load the sprint spec for decision context:

  1. Find docs/sprints/sprint-<number>.md (derive number from branch name)
  2. Extract and hold in context:
    • Sprint goal — the primary decision-making context for this story. When implementation choices are ambiguous, the sprint goal breaks the tie.
    • Boundaries — out-of-scope items. If this story drifts toward an out-of-scope area, flag it.
    • Remaining capacity — count stories by status and size (S=1, M=2, L=4 sessions). Compare against total available sessions to determine sprint health.
    • Decisions log — prior decisions in this sprint that may constrain this story's approach.

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 /handoff at natural break points to preserve context."

This is guidance, not enforcement — the developer may complete it in fewer sessions.

0b. PRD Scope Guard

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.

0b.5. Discovery Context Loading

<IF condition="docs/reference/DECISION_LOG.md exists"> Load decisions relevant to this story (grep for keywords from story description and affected files). During implementation: if a decision point arises that's already in the log, USE the logged decision. State: > "Using decision D007 (logged during discovery): [decision]" Do NOT re-decide settled questions. If a decision needs revisiting, document why and update the log. </IF><IF condition="docs/reference/ASSUMPTION_REGISTER.md exists"> Load assumptions relevant to this story (grep for keywords from story description). If implementation reveals an assumption is wrong, update the register: set status → INVALIDATED, add evidence in the Evidence column. Flag to the user: > "Assumption A003 has been invalidated: [assumption]. Evidence: [what we found]. This may affect [related decisions]." </IF><IF condition="Story has a 'No-Gos' section OR vision/project-pitch.md contains NO-GOS"> Load No-Gos into context. If scope creep toward a No-Go is detected during implementation, STOP: > "This is heading toward a documented No-Go: [no-go]. Should we continue or respect the boundary?" </IF>

0c. Scope Analysis

Before any exploration, decompose the user's request. Apply the scope_analysis reasoning tool from references/reasoning-tools.md:

  1. List ALL distinct outcomes the user expects (implementation, tests, docs, PR, etc.)
  2. For each: identify type, files likely affected, complexity (1-5), and dependencies
  3. Flag any deliverable rated complexity ≥4 as candidate for splitting
  4. If the request contains multiple independent stories, suggest splitting and confirm scope
  5. Confirm the full scope with the user before proceeding to planning

This prevents missing later parts of compound requests (e.g., "refactor auth AND add rate limiting AND create a PR").

Size & Risk Classification (Fast-Track Gate)

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:

SizeCriteriaDefault Workflow
TRIVIALSingle file, <10 lines changed, no behavioral change (typo, config, comment)Phase 3-lite (below)
SMALLOne clear change following an existing patternLightweight Phase 1 (skip 1f, 1g) → Phase 2 → Phase 3 → Phase 4
STANDARDOne coherent feature, requires a planFull workflow (unchanged)
LARGEOne coherent mechanism whose parts interlock and cannot be meaningfully tested in isolationFull workflow + integration test pass before Phase 4
XLA complete subsystem with a single conceptual centerFull 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:

  • If stories matching this type consistently required full workflow despite SMALL classification → escalate to STANDARD
  • If STANDARD stories in this area consistently completed without issues → note as candidate for lightweight treatment
  • Log calibration adjustment in plan for transparency: Depth calibration: [escalated/standard/downgraded] based on [N] prior executions

Sprint context modifier (from Phase 0a.5): If sprint context was loaded, apply:

  • Sprint-aligned stories: maintain or escalate depth — these are goal-critical, quality matters most
  • Sprint-peripheral stories: consider downgrading depth if sprint capacity is tight — keep scope minimal, defer stretch goals to next sprint
  • Log: 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)
TRIVIALPhase 3-litePhase 3-lite + full test suiteReclassify as SMALL
SMALLLightweight Phase 1Standard workflowStandard + mandatory security-audit
STANDARDStandard workflowStandard + all quality agentsStandard + all agents + architecture-check
LARGEStandard + integration testsStandard + all quality agents + integration testsStandard + all agents + architecture-check + security-audit
XLStaged build + all quality agentsStaged build + all agents + architecture-checkStaged build + all agents + architecture-check + security-audit + integration-tester
<HARD-GATE> **Red flag:** If editing multiple files or changing observable behavior, STOP and reclassify as STANDARD. Fast-track is for genuinely trivial changes only. </HARD-GATE>

SMALL Story Checklist

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:

  • Phase 0: Intent decomposition
  • Phase 1: Lightweight analysis + plan (includes 1c.5 Research Decision — MANDATORY output) → *** HARD GATE: user approval ***
  • Phase 2: Context transition + readiness gate (5 objective checks) → *** HARD GATE ***
  • Phase 3: Implementation (TDD by story type)
  • Phase 4: Self-review + quality gates + completion verification with evidence → *** 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.

Phase 3-lite (TRIVIAL only)

  1. Make the change
  2. Run tests (if test command configured)
  3. Abbreviated self-review: Does the diff match intent? Any unintended side effects?
  4. Commit with conventional format
  5. Print completion report

Phase 1: Story Analysis (Plan Mode)

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.

1a. Identify Story Type

Determine the story type from the description, backlog entry, or user input:

TypeIndicatorsApproach
FeatureNew user-facing capability, "As a user..."TDD: RED-GREEN-REFACTOR
Bug FixDefect, "fix", error report, reproduction stepsReproduce → Test → Fix → Verify
Refactoring"Refactor", "restructure", no behavior changeCharacterization tests → Refactor → Verify
Spike/Research"Investigate", "evaluate", "prototype", time-boxedExplore → Document → Decide
InfrastructureCI/CD, tooling, build, config, environmentPlan → 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
ReviewPhase transition, walkthrough, assumption validation, direction decisionInteractive 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:

  • Feature — description: "Full TDD (RED-GREEN-REFACTOR). AC in Given/When/Then. Heaviest testing."
  • Bug Fix — description: "Reproduce first, then fix. Creates regression test. Lighter planning."
  • Refactoring — description: "No behavior change. Characterization tests first, then restructure."
  • Spike/Research — description: "Time-boxed exploration. Output is a decision doc, not code. No TDD."
  • Infrastructure — description: "CI/CD, tooling, config. Smoke test verification. Lighter AC."
  • Testing — description: "Pure test code. Design strategy, generate tests, validate coverage."
  • Documentation — description: "Non-code deliverable. Gather, generate, review cycle."
  • Security — description: "Threat model first. Mandatory security-audit agent. CWE checklist."
  • Performance — description: "Baseline measurement required. Optimize, then benchmark."
  • Skill/Tooling — description: "Developer experience. Design, build, document pattern."

1b. Codebase Exploration (Grep-First)

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:

SizeExploration Strategy
TRIVIALSkip Phase 1b entirely (already fast-tracked)
SMALLSingle grep-first pass: extract terms from the story, run parallel Grep calls, read top 5-7 files
STANDARDGrep-first pass + 1-2 codebase-explorer agents for broader context (architecture focus, test focus)
STANDARD + High-riskGrep-first pass + 2 agents + security-focused grep (search for auth patterns, input validation, trust boundaries in affected modules)

Grep-first process:

  1. Extract key terms from the story description (function names, module names, API endpoints, error messages)
  2. Run parallel Grep calls: imports/usage, definitions, and test references
  3. Rank files by match density, select top 5-10
  4. If fewer than 3 files match (greenfield or entirely new feature): fall back to codebase-explorer agents

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:

  • Implementation focus: "Find source files that implement or relate to: [story description]."
  • Test focus: "Find test files, test utilities, and fixtures related to: [story description]."

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:

  • Low severity + Hours effort in files being modified → suggest addressing as a "boy scout" improvement alongside the story (leave code better than you found it). Note: do not expand story scope — only fix if genuinely trivial.
  • Higher severity or effort → note in exploration summary for awareness ("TD-NNN affects this file"), but do not expand scope. The debt register tracks these for future sprints.

1c. Research Codebase

  • Deep-read the files identified in step 1b
  • Understand patterns, conventions, and existing tests in the area
  • If docs/context/system-patterns.md exists and is populated (not template-only), check it against the files being touched:
    • Which implementation patterns apply to this story's scope? (Note reference files to follow.)
    • Does the area's error handling match the documented strategy? (Flag divergence.)
    • What testing conventions apply? (Test naming, fixture approach, mock strategy.)
    • Is there an implementation recipe for the type of entity this story adds? (Follow it.) Note applicable patterns in the plan's "patterns to follow" section. If the story will introduce a NEW pattern not yet documented, note that for post-implementation update.
  • Identify files to modify and files to create
  • Check for CLAUDE.md files in the target directory and parent directories — these contain module-specific patterns and conventions that supplement global CLAUDE.md

1c.5. Online Verification

<HARD-GATE> **This phase produces MANDATORY output.** You MUST print a `## Research Decision` block (format below) before proceeding to Phase 1d. The plan CANNOT be written without this block. Skipping this phase silently is a workflow violation. </HARD-GATE>

Step 1 — Classify research requirement:

Story typeResearch requirementDepth
Spike/ResearchMANDATORYDEEP
SecurityMANDATORYSTANDARD
Bug FixMANDATORY (error pattern search)QUICK
All other typesConditional (evaluate 3 signals below)Auto-select

Step 2 — For conditional stories, evaluate these three signals:

SignalResearch neededSkip research
Risk levelHigh-risk topics: security, payments, auth, external APIs, new dependenciesLow-risk internal changes
Local context strengthWeak: unfamiliar library, no existing patterns, no prior solutions in docs/solutions/Strong: established patterns, existing tests, prior solution docs cover this area
Uncertainty levelApproach is unclear, multiple valid strategies existApproach 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 contextResearch depth
Spike/ResearchDEEP
Security, new external dependenciesSTANDARD
Bug fix, standard story with research signalsQUICK

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:

  • If official docs reveal a deprecation or API change: note it in the plan as a "Doc Finding" and update relevant reference docs after implementation
  • If a better approach is found: incorporate it into the plan
  • If everything checks out: note "Online verification: APIs confirmed current" and move on

1c.5+. Dependency Freshness Check (Always-On for External Deps)

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

  1. Identify the external libraries the story will use (from plan or codebase grep)
  2. For each, WebSearch for: "<library> <pinned-version> deprecation OR breaking change OR CVE" (batch into 1-2 searches)
  3. If a result looks relevant, WebFetch the specific page to confirm

Outcomes:

FindingAction
No issuesNote "Dep freshness: all clear" in plan, move on
Deprecation noticeNote in plan, use recommended replacement API
Known CVEFlag to user immediately — may change story scope
Breaking change in newer versionNote in plan for awareness; no action if pinned version is stable

Skip when: Story only touches internal code with no external library calls.

1d. Define Required Skills

Determine which skills benefit this story. If the story metadata already defines skills, use those. Otherwise select from:

SkillLoad When
/code-qualityFeature, refactoring, infrastructure stories
/test-validatorFeature, bug fix, refactoring, testing stories
/security-auditSecurity 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).

1d.5. Discovery Gate (Facilitator Check)

Before writing the plan, check: do you have enough information to write a plan without assumptions?

  • If YES: proceed to 1d.7
  • If NO: present the 3 most critical unknowns to the user as focused questions with 2-4 answer options each. Integrate answers, then proceed to 1d.7.

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.

1d.7. Story Refinement & Forward Context

With codebase understanding from 1b-1c, pressure-test the story before planning:

  1. Map to application: For each acceptance criterion, identify the concrete components, endpoints, services, and modules involved. If a criterion is vague, make it specific to the project's architecture.
  2. Gap analysis: What's needed for this to work that the story doesn't mention? Check if gaps are covered by other TODO stories in the epic.
    • Small uncovered gap → propose expanding this story's AC (confirm with user)
    • Large uncovered gap → flag it, don't silently absorb scope
  3. Forward context: Check TODO stories in the same epic that depend on or relate to this one. If research clarifies anything for them (API shape they'll consume, patterns to follow, components to reuse), add a brief > 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.

1e. Write the Plan

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:

  1. Specification (WHAT/WHY) — User-visible behavior changes, acceptance criteria in Given/When/Then format. NO file paths, NO function names, NO framework references.
  2. Implementation Approach (HOW) — Files to modify/create, patterns to follow, technical strategy with rationale.

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.

<IF condition="docs/adr/ contains ADR files"> Scan ADR YAML frontmatter for `status: accepted` records with tags relevant to this story's domain. Check that no proposed approach matches a `rejected-options` value in any accepted ADR. If a match is found, note the ADR reference and use the chosen alternative instead. Check `Reconsider when` conditions only if circumstances have materially changed. </IF><IF condition="docs/reference/GROUND_RULES.md exists"> Check the plan against `docs/reference/GROUND_RULES.md`. Any MUST violation → HALT. Any SHOULD violation → document justification in an Architectural Violations table (see `references/plan-template.md`). </IF>

1f. Clarification Check

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

<IF condition="ambiguity_scan produces questions OR plan contains [NEEDS CLARIFICATION] markers"> Present questions to user. Integrate answers into the plan. Remove resolved `[NEEDS CLARIFICATION]` markers. </IF>

1g. Plan Completeness

Apply the plan_completeness reasoning tool from references/reasoning-tools.md to verify:

  • All deliverables from Phase 0 have implementation steps
  • All acceptance criteria have verification approaches
  • Specification section contains zero implementation details
  • Implementation section traces to every acceptance criterion
  • Research Decision block is present (from Phase 1c.5) — if missing, HALT and go back to 1c.5

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"

File Context (accumulates across compactions)

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

<HARD-GATE> **POST-PLAN-MODE EXECUTION — THIS IS NOT OPTIONAL**

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:

  1. Read .claude/skills/story-cycle/SKILL.md starting from ## Phase 2: Context Transition + Confidence Gate
  2. Execute the remaining_steps from the plan's Story-Cycle Context block IN ORDER
  3. Do NOT report completion until Phase 4d passes with evidence for every acceptance criterion

The 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. </HARD-GATE>

For complex stories, use ultrathink to reason through architectural decisions before writing the plan.

1h. Depth Check (Optional)

Before presenting for approval, offer the user a depth option if the plan contains areas with complexity ≥4 or unresolved uncertainties:

  • [D] Deep dive — Explore design alternatives for uncertain areas using the depth_exploration reasoning tool and elicitation techniques from references/elicitation-techniques.md
  • [C] Continue — Plan is ready for approval as-is

If [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.

<HARD-GATE> Do NOT write any implementation code, edit source files, or take any implementation action until the plan has been presented and the user has explicitly approved it. "I already know what to do" is NOT approval. Wait for the user. </HARD-GATE>

Phase 2: Context Transition + Confidence Gate

After plan approval, prune context and score confidence in a single pass.

2a. Context Pruning

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.
  • Target source/test files from the plan. SKIP until Phase 4: 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.

2b. Readiness Gate

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.

ResultAction
All 5 passProceed to Phase 3
Any failAddress the specific gap (re-read missing files, run tests, check rules)
User overrideProceed with acknowledgment of overridden checks
<HARD-GATE> Do NOT skip the readiness gate for ANY story size except TRIVIAL. Output the 5-check results before proceeding to Phase 3. </HARD-GATE>

Phase 3a: Parallel Stream Analysis (Optional)

<IF condition="story is STANDARD size AND risk is Low or Medium (3-6) AND plan identifies ≥2 independent work units"> Analyze the approved plan for parallel execution opportunities. Read `references/parallel-streams.md` for the full protocol.
  1. Map each work unit to its file scope (which files it creates/modifies)
  2. Check for file overlaps — if ANY file appears in multiple streams, merge those streams
  3. If ≥2 non-overlapping streams exist, present the stream analysis to the user
  4. If user approves: create worktrees per stream, dispatch agents, coordinate merges
  5. If user declines or streams overlap: proceed to serial Phase 3</IF>
<ELSE> Skip — proceed directly to Phase 3. </ELSE>

Session Recovery

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.

Phase 3: Execute by Story Type

3.pre. Git Checkpoint

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

Intermediate Commits During Implementation

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:

  • Prevent data loss if the session crashes mid-implementation
  • Provide natural rollback points within a story
  • Are squashed at sprint-end anyway — commit freely during development
  • Should each leave the codebase in a working state (tests pass)

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.

<HARD-GATE> **TDD Ordering Enforcement (Feature, Bug Fix, Refactoring stories):**

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

  1. Write a failing test for the first behavior (RED) — run it, show the failure output
  2. Only THEN write the minimum implementation to make it pass (GREEN)
  3. Refactor while keeping tests green
  4. Repeat for each behavior in the acceptance criteria

Bug Fix stories:

  1. Write a reproduction test that captures the bug (must FAIL) — run it, show the failure output
  2. Only THEN implement the fix
  3. Verify the reproduction test now passes

Refactoring stories:

  1. Write characterization tests that capture current behavior (must PASS) — run them, show the output
  2. Only THEN perform the refactoring
  3. Verify characterization tests still pass after each step

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. </HARD-GATE>

When errors occur during execution, consult references/error-recovery.md — search for ## Phase 3 for the recovery table.

Web-Assisted Error Recovery (Phase 3)

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:

  • Sub-questions (1-2, generated from the error):
    1. "What does [error message snippet] mean in [library/framework] [version]?"
    2. "How to fix [error pattern] in [library] [version]?"
  • Output format: evidence-check (fix or workaround with source citation)
  • Apply the fix if found. If no results: fall back to normal error recovery (re-read code, check types, etc.)

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.

Phase 4: Verify + Wrap Up

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.

4a. Self-Review + Disaster Prevention

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.

<HARD-GATE> Do NOT skip self-review for ANY story size. If any checklist item fails, go back to Phase 3 and fix before continuing. </HARD-GATE>

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:

  1. Load the persona(s) referenced in the story's Personas: field
  2. Check user-facing text: Do error messages, labels, or instructions use jargon that conflicts with the persona's CONTEXT (tech proficiency)?
  3. Check interaction patterns: Does the UI/UX match the persona's BEHAVIORS (e.g., keyboard navigation for accessibility, mobile-first for mobile personas)?
  4. Check the persona's FAILURE LOOKS LIKE scenarios: Is any of them possible in this implementation?

Focus 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 InvocationNotes
Low (3-4)/quality-check (profile defaults)Standard: code+tests+security. Lean: code only.
Medium (5-6)/quality-check --code --tests --securityPlus integration-tester at standard+ profiles
High (7-9)/quality-check --allAll 5 agents + integration-tester (mandatory)
<IF condition="Profile is strict"> **Strict override:** Dispatch `/quality-check --all` for ALL stories regardless of risk level. Integration-tester is mandatory for all stories. </IF><IF condition="Profile is lean"> **Lean override:** Skip quality agent dispatch. Phase 4b quality-gate-sequence (lint + test) is sufficient. </IF>

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.

4b. Quality Gates

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.

<IF condition="test command exists in CLAUDE.md Commands"> Execute the configured quality commands. Verify all pass with zero failures. </IF> <ELSE> Run any configured commands (lint, typecheck). No test command configured — skip test verification, note in completion report. </ELSE><HARD-GATE> Do NOT proceed to Phase 4c/4d until ALL configured quality gates pass with zero failures. Show the passing output in the current turn. "It passed earlier" is not evidence — re-run if any code changed since the last run. </HARD-GATE>

4c. Generate UAT Test Case (Optional)

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.

  1. Find UAT location: Check for docs/testing/UAT_COVERAGE.md (single-file), docs/testing/uat/ (directory), or tests/uat/scenarios/. If none exists, skip this phase entirely.
  2. Find next UAT ID: Search for ### UAT- headings in existing files, increment the highest number, format as UAT-### (zero-padded to 3 digits).
  3. Generate test case matching the template format in UAT_COVERAGE.md:
    • ### 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 row
  4. Write the test case:
    • Single file (docs/testing/UAT_COVERAGE.md): Append before the ## Reference section
    • Directory (docs/testing/uat/ or tests/uat/): Create a new file following existing naming convention
  5. Update Dashboard: Increment "Total Test Cases" and "⬜ Untested" counts in the Dashboard table

4c.1. Sense Check UAT Case (Optional)

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

  1. Trace each UAT step through the code just written:
    • Does the action map to a real UI element / API endpoint / code path?
    • Is the assertion verifiable from the implementation?
    • Are there any steps that reference behavior not actually implemented?
  2. Verify acceptance criteria coverage:
    • Each UAT acceptance criterion should correspond to tested, reachable code
    • Flag any criterion that assumes functionality beyond what was built
  3. Assign verdict:
    • Pass — all steps and criteria trace to working code
    • Warning — potential gap found; note the issue in the UAT file and fix if trivial
    • Fail — step references non-existent behavior; fix the UAT case (not the code — the code was already tested)
  4. Update the UAT file:
    • Check the box: - [x] Logic verified from code perspective
    • Fill in Notes with verdict and what was checked

4d. Completion Verification

Re-read the original acceptance criteria from the plan. For each criterion, provide concrete evidence: test output, code reference (file:line), or command output.

<LOOP max="2" until="all acceptance criteria have evidence"> If any criterion lacks evidence: identify the gap, loop back to Phase 3 for that specific item, re-verify. </LOOP><HALT reason="max verification loops exhausted"> Report what IS complete with evidence, list remaining gaps.

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. </HALT>

<HARD-GATE> Do NOT print the completion report until every acceptance criterion has been verified with evidence. Show test output or code references — not assertions. </HARD-GATE>

4e. Docs + Commit

  1. Capture story outcome: Run the 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.
  2. Update epic file (docs/reference/backlog/E##-*.md):
    • In story checklist: change - [ ] ID — Title (P#, in-progress) → - [ ] ID — Title (P#, review)
    • In story detail section: update **Status:** review
    • Legacy format: mark as [DONE] if epic uses old markers
    • Check all acceptance criteria boxes in the detail section (- [ ] → - [x])
    • Emit story lifecycle event:
      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
  3. Update docs/reference/BACKLOG_INDEX.md: Update story counts per priority group in the status table.
  4. Update 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.
  5. Update documentation only if the story's AC requires it
  6. Architecture documentation check: Read the Update Triggers section of 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:
    • If a non-obvious gotcha was discovered during implementation → add to Known Landmines
    • If a significant architectural choice was made → add to Key Decisions with trade-off
    • If no Update Trigger matches, skip
  7. Capture learnings (optional): If non-obvious patterns discovered, run the capture-learnings micro-component from .claude/prompts/capture-learnings.md to save to docs/solutions/<topic-slug>.md
  8. Clean up checkpoint: Delete the git checkpoint tag from Phase 3.pre: git tag -l 'story-checkpoint-*' | xargs -r git tag -d
  9. Commit: Invoke the /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

Completion Report

### 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

Recovery

For phase-specific error recovery, consult references/error-recovery.md — search for the relevant ## Phase N section.

General recovery:

  • Test failure (new code): Read the error, fix the implementation, re-run. Do not weaken the test.
  • Test failure (pre-existing): Inform user. Do not mask it. Log to docs/technical-debt.md if out of scope.
  • Context exhaustion: Save current progress to docs/plans/, commit work-in-progress, inform user to start a new session with /continue.
  • Git conflict: Show conflict to user. Do NOT auto-resolve without approval.
  • Skill not found: If a required skill (e.g., /code-quality) is not available, skip it and note in the completion report.
  • Implementation fundamentally wrong: If Phase 4 reveals the approach is flawed, use the checkpoint rollback option (Phase 4d) to cleanly revert to pre-implementation state.

Rules

  • NEVER skip the plan phase — always enter plan mode first
  • NEVER carry exploration context into execution — clear and reload
  • NEVER merge to main or create a PR — that's sprint-end
  • NEVER add features not in the acceptance criteria
  • NEVER weaken or delete existing tests
  • Follow coding standards in docs/reference/CODING_STANDARDS.md
  • Follow testing strategy in docs/reference/TESTING_STRATEGY.md
  • Follow architecture constraints in docs/architecture/ARCHITECTURE.md
  • Follow project ground rules in docs/reference/GROUND_RULES.md (if exists)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.