246 lines
8.8 KiB
Markdown
246 lines
8.8 KiB
Markdown
# 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
|