pixelheros/docs/examples/session-gate-check-phase-transition.md

Example Session: /gate-check Phase Transition — Systems Design → Technical Setup

Context: Solo indie dev, end of week 5. The Systems Design phase feels complete — 6 MVP GDDs written, cross-review done, engine set up. User wants to formally advance to Technical Setup.

Starting State:

• production/stage.txt — currently systems-design
• design/gdd/systems-index.md — 6 MVP systems listed, all marked Status: GDD Complete
• design/gdd/ — 6 GDD files present
• design/gdd/gdd-cross-review-2026-03-10.md — cross-review report, verdict: CONCERNS (1 low-priority note)
• Engine configured (Godot 4.6, /setup-engine complete)

Session Duration: ~20 minutes Turns: 7 Outcome: Gate passed, stage.txt updated to technical-setup, clear list of what comes next

---

Turn 1: User Initiates Gate Check

User:

/gate-check

Turn 2: Agent Detects Current Phase and Runs the Check

Agent (via /gate-check):

Reading production/stage.txt — current phase: systems-design

Running gate: Systems Design → Technical Setup

---

Required Artifacts Checklist:

Artifact	Requirement	Status
design/gdd/systems-index.md	Exists, all MVP systems listed	✅
Per-system GDDs	All MVP systems have a GDD	✅ (6/6)
/design-review per GDD	Each GDD reviewed	✅ (6/6 review comments found)
Cross-GDD review report	design/gdd/gdd-cross-review-*.md exists	✅
Cross-review verdict	PASS or CONCERNS (not FAIL)	✅ CONCERNS
Engine configured	production/stage.txt or CLAUDE.md engine entry	✅ Godot 4.6

---

Content Scan:

Checking GDD completeness (8 required sections each)...

GDD	Missing Sections
movement-system.md	None ✅
stamina-system.md	None ✅
combat-system.md	None ✅
inventory-system.md	None ✅
crafting-system.md	None ✅
exploration-system.md	None ✅

---

Cross-Review Concerns (from gdd-cross-review-2026-03-10.md):

1. ⚠️ LOW — Crafting and inventory both define "item stack size" independently with different defaults (crafting: 99, inventory: 64). One system should be the authority; the other should reference it. Not blocking — can resolve in ADR.

---

Verdict: PASS

All required artifacts present. Cross-review concern is LOW severity and can be resolved during Technical Setup via an ADR. This is a normal finding at this stage.

May I advance production/stage.txt to technical-setup?

Turn 3: User Confirms

User:

Yes, advance it.

Turn 4: Agent Updates Stage and Presents Next Steps

Agent:

Updated production/stage.txt → technical-setup

---

You are now in: Technical Setup

This phase establishes the technical foundation before production coding starts. Your goal is a complete, approved architecture so that every story written in Pre-Production has clear, unambiguous technical guidance.

Required steps this phase (in order):

1. /create-architecture — Author the master architecture document. Covers system decomposition, data flow, layer boundaries, and module responsibilities.

2. /architecture-decision (one per significant technical choice) — At minimum:

   • Rendering approach (2D camera, viewport, etc.)
   • Save/load strategy
   • Audio bus architecture
   • The "item stack size authority" issue from cross-review (crafting vs inventory)

3. /architecture-review — Validates all ADRs for completeness, dependency ordering, and GDD traceability. Produces the TR-registry.

4. /create-control-manifest — Converts Accepted ADRs into a flat programmer rules sheet. This is what implementation agents will consult during coding.

5. /gate-check — Technical Setup → Pre-Production gate. Requires: architecture doc, all ADRs Accepted, control manifest, and dependency ordering resolved.

Optional but recommended:

• /tech-debt scan if you have any prototype code you plan to carry forward
• /setup-engine re-run if you haven't yet fetched Godot 4.6 API snapshots

Tip: Start with /architecture-decision for the item stack size conflict. It's a quick win that closes an open question before it creates ambiguity in two ADRs later.

Turn 5: User Asks About the Cross-Review Concern

User:

What do I actually write in the ADR for the stack size conflict?

Turn 6: Agent Advises

Agent:

The ADR decision is: which system owns the canonical max_stack_size value?

Two options to consider:

Option A: Inventory owns it

• ItemData resource (owned by inventory) gets max_stack_size: int = 64
• Crafting system reads from ItemData, never sets its own value
• Pros: inventory is the source of truth for all item properties
• Cons: crafting team needs to know to look at inventory data

Option B: Item data resource owns it (shared resource)

• ItemData.max_stack_size is the authority for both systems
• Both crafting and inventory import from ItemData
• Pros: single source, no coupling between crafting and inventory modules
• Cons: one more thing in the shared data layer

Most studios go with B (shared resource) once they have >2 systems touching item data. But either is valid for a solo project.

Run /architecture-decision and it will guide you through the ADR format, including the Dependencies section that links this ADR back to the two GDDs.

Turn 7: User Wraps Up

User:

Got it. I'll start with /architecture-decision for this.

Agent:

Good starting point. The ADR will document the decision, the reasoning, and the GDD requirements it addresses — so when you write code months from now, the rationale is preserved.

Your phase gate is logged. Run /help at any time during Technical Setup to see your current progress against the required checklist.

---

What This Example Demonstrates

• Gate check is automated, not manual: agent reads artifacts and checks them — user doesn't fill out a form
• CONCERNS ≠ FAIL: the cross-review concern is LOW severity and passes the gate. A FAIL would require resolution before advancing.
• Stage.txt is the authority: the status line, /help, and all skills read from production/stage.txt — updating it here changes what every subsequent skill sees
• Next steps are phase-specific: the agent doesn't give a generic "good luck" — it gives the ordered checklist for Technical Setup specifically
• Gate check surfaces carry-forward work: the stack size conflict was a cross-review note; the gate check ensures it becomes a concrete ADR rather than getting lost
• One advance per gate: the user confirmed advancement explicitly. The gate doesn't auto-advance; human confirmation is required.