# Example Session: Full Story Lifecycle — /story-readiness → Implement → /story-done

**Context:** Solo indie dev, mid-production sprint. The movement system GDD and architecture are complete. A story for movement's core implementation has been generated by `/create-stories`.

**Starting State:**
- `design/gdd/movement-system.md` — complete, all 8 sections
- `docs/architecture/movement-adr-001.md` — Status: Accepted
- `production/sprints/sprint-03.md` — lists STORY-MOV-001 in backlog
- `production/stories/STORY-MOV-001.md` — exists but not yet validated
- No implementation code yet

**Session Duration:** ~50 minutes
**Turns:** 13
**Outcome:** Story validated ready, implemented, verified complete with `/story-done`

---

## Phase 1: Story Readiness Check

### Turn 1: User Runs Readiness Check

**User:**
> /story-readiness production/stories/STORY-MOV-001.md

### Turn 2: Agent Validates the Story

**Agent (via /story-readiness):**
> Reading `production/stories/STORY-MOV-001.md`...
>
> **STORY-MOV-001: Implement CharacterBody2D movement with terrain modifiers**
>
> Running 4 validation checks:
>
> **1. Design Completeness**
> - GDD referenced: `design/gdd/movement-system.md` ✅
> - GDD section coverage: Detailed Rules ✅, Formulas ✅, Edge Cases ✅
> - TR-IDs embedded: TR-MOV-001 through TR-MOV-008 ✅
>
> **2. Architecture Completeness**
> - ADR referenced: `docs/architecture/movement-adr-001.md` ✅
> - ADR status: **Accepted** ✅ *(Would be BLOCKED if Proposed)*
> - Control manifest version in story: `2026-03-10` — current manifest is `2026-03-10` ✅
>
> **3. Scope Clarity**
> - Acceptance criteria: 9 items, all measurable ✅
> - Out-of-scope items listed: swimming, climbing ✅
> - Ambiguities found: **1**
>   - ⚠️ Story says "roll direction follows last input direction" but GDD says "roll in movement direction" — these conflict when player stops and immediately rolls. Clarify before pickup.
>
> **4. Definition of Done**
> - Tests required: unit tests for formula functions ✅
> - Integration signal: `on_stamina_event` must fire correctly ✅
>
> ---
> **Verdict: NEEDS WORK**
>
> One ambiguity must be resolved before implementation starts. Would you like to resolve it now so I can mark the story as ready?

### Turn 3: User Resolves the Ambiguity

**User:**
> Roll uses last movement direction. If player is standing still, roll uses facing direction instead.

### Turn 4: Agent Updates the Story

**Agent:**
> Updating the story's Detailed Rules section:
>
> > Roll direction: last movement direction. If velocity is zero at roll input, roll uses current facing direction.
>
> May I write this to `production/stories/STORY-MOV-001.md` and set Status to `ready-for-dev`?

**User:**
> Yes

**Agent writes update. Story status: `ready-for-dev`.**

> **Verdict: READY**
> Story is implementation-ready. Pick it up when you're ready to build.

---

## Phase 2: Implementation

### Turn 5: User Starts Implementation

**User:**
> Let's implement STORY-MOV-001. I'm ready to start coding.

### Turn 6: Agent Reads Story and ADR

**Agent (gameplay-programmer):**
> Reading `production/stories/STORY-MOV-001.md`, `design/gdd/movement-system.md`, and `docs/architecture/movement-adr-001.md`...
>
> **Architecture (from ADR-001):**
> - `MovementComponent.gd` — attached to player scene, not a singleton
> - Terrain modifier lookup via `TerrainLayer.get_modifier(tile_position)` helper
> - Stamina events via signal (not direct call to StaminaSystem)
>
> **My proposed file structure:**
> ```
> src/gameplay/movement/
>   movement_component.gd       # CharacterBody2D logic, state machine
>   terrain_modifier_table.gd   # Const table: terrain_type -> {speed_mod, drain_mod}
> tests/unit/
>   test_movement_formulas.gd   # Unit tests for speed/drain calculations
> ```
>
> May I proceed with this structure?

**User:**
> Yes

### Turn 7: Agent Implements and Shows Key Code

**Agent:**
> Implementing `movement_component.gd`. Key excerpt for your review before I write the file:
>
> ```gdscript
> class_name MovementComponent
> extends Node
>
> signal stamina_event(type: String, amount: float)
>
> @export var base_walk_speed: float = 120.0
> @export var run_multiplier: float = 1.7
> @export var stamina_drain_walk: float = 2.0
> @export var stamina_drain_run: float = 6.0
> @export var stamina_cost_roll: float = 15.0
>
> var _is_carrying_heavy: bool = false
>
> func _physics_process(delta: float) -> void:
>     var terrain_mod := _get_terrain_modifier()
>     var effective_speed := _calculate_speed(terrain_mod)
>     # ...
> ```
>
> All values are `@export` — none hardcoded. Is this the direction you want?

**User:**
> Looks good. Write it.

### Turn 8–9: Agent Writes Files and Tests

**Agent writes:**
- `src/gameplay/movement/movement_component.gd`
- `src/gameplay/movement/terrain_modifier_table.gd`
- `tests/unit/test_movement_formulas.gd`

**Agent:**
> Files written. Running available linting checks...
>
> No errors. Tests file created with 6 unit tests covering:
> - Walk speed formula (3 terrain types)
> - Run speed formula
> - Stamina drain calculation
> - Roll stamina cost (with and without zero-velocity edge case)
>
> Manual testing needed for: invincibility frames, slope blocking, terrain integration (requires running scene).

---

## Phase 3: Story Completion

### Turn 10: User Tests Manually and Runs /story-done

**User:**
> I've tested it in the scene — everything works. /story-done production/stories/STORY-MOV-001.md

### Turn 11: Agent Runs Completion Review

**Agent (via /story-done):**
> Reading story, GDD, ADRs...
>
> **Phase 1: Story Located** ✅ `production/stories/STORY-MOV-001.md`
>
> **Phase 2: Acceptance Criteria Verification**
>
> | # | Criterion | Verification | Status |
> |---|-----------|--------------|--------|
> | 1 | Walk speed correct on normal ground | Auto: formula unit tests pass | ✅ AUTO |
> | 2 | Run speed correct | Auto: formula unit tests pass | ✅ AUTO |
> | 3 | Run cancels at stamina 0 | Manual: user confirmed | ✅ MANUAL |
> | 4 | Roll invincibility frames work | Manual: user confirmed | ✅ MANUAL |
> | 5 | Terrain modifiers apply correctly | Manual: user confirmed | ✅ MANUAL |
> | 6 | Heavy carry disables run | Auto: not yet testable (inventory not integrated) | ⏳ DEFERRED |
> | 7 | Stamina signals fire correctly | Auto: integration test pending | ⏳ DEFERRED |
> | 8 | No hardcoded values | Auto: grep for magic numbers → 0 found | ✅ AUTO |
> | 9 | Slopes >45° block movement | Manual: user confirmed | ✅ MANUAL |
>
> **Phase 3: GDD/ADR Deviations**
>
> Scanning implementation against TR-IDs...
>
> - TR-MOV-001 through TR-MOV-007: ✅ Implemented as specified
> - TR-MOV-008 (heavy carry signal): ⚠️ ADVISORY — deferred to inventory integration story. Not a deviation, just unverifiable now.
>
> **Phase 4: Manifest Staleness Check**
>
> Story control manifest version `2026-03-10` matches current manifest `2026-03-10`. ✅
>
> **Phase 5: Code Review Prompt**
>
> Suggest running `/code-review src/gameplay/movement/` before marking complete. Not blocking.
>
> ---
> **Completion Report: COMPLETE WITH NOTES**
>
> Story is complete. Two criteria deferred to inventory integration — log as deferred, not blocked.
>
> May I update the story status to `Status: Complete` and add Completion Notes, and update `production/sprint-status.yaml`?

**User:**
> Yes

### Turn 12: Agent Closes the Story

**Agent writes:**
- Story `Status: Complete` + Completion Notes (deferred criteria noted)
- `production/sprint-status.yaml` — STORY-MOV-001 set to `done`

**Agent:**
> STORY-MOV-001 closed.
>
> **Deferred criteria logged** (will auto-surface in inventory integration story):
> - Heavy carry disables run (requires inventory signal)
> - Stamina signal integration test (requires stamina system)
>
> **Next ready story from sprint:**
> - STORY-MOV-002: Stamina system — this is the logical next story (downstream dep now unblocked)
> - STORY-HUD-001: Movement HUD indicators — also unblocked
>
> Run `/story-readiness` on whichever you pick up next.

---

## What This Example Demonstrates

- **Readiness gate catches real issues**: the roll direction ambiguity would have caused a late implementation decision without `/story-readiness`
- **ADR status is a hard gate**: if `movement-adr-001.md` had been `Proposed` instead of `Accepted`, story would be `BLOCKED` and implementation wouldn't start
- **Deferred criteria**: not every acceptance criterion can be verified at story close — `/story-done` tracks deferred items rather than blocking completion
- **TR-ID references**: story stores `TR-MOV-001` IDs, not quoted GDD text — avoids false deviation flags when GDD wording is cleaned up later
- **sprint-status.yaml**: single source of truth for sprint state, updated by `/story-done` and read by `/sprint-status`
- **Manifest version check**: ensures story's implementation guidance hasn't drifted from current architecture decisions