Claude-Code-Game-Studios/docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md

Multi-Stage Document Workflow

Problem: Some design documents are too large or complex to complete in a single session. An inventory system GDD might need multiple rounds of work across several days.

Solution: Use incremental document creation with clear WIP markers.

---

📋 When to Use Multi-Stage Workflow

Use this approach when:

• Document is large (inventory + items + crafting might be one big GDD)
• Design needs time to evolve (you want to think on it overnight)
• Multiple stakeholders need input (waiting for feedback before continuing)
• Context is getting full (~70%) before doc is complete
• User explicitly wants to work incrementally ("Let's do sections 1-4 today")

---

✅ How It Works: Incremental Document Creation

Session 1: Start the Document

User: "Let's design the inventory system, but I only have 30 minutes today.
      Can we do the first few sections and continue tomorrow?"

Agent: "Absolutely! For an inventory GDD, here's my proposed session breakdown:

       **Session 1 (today, ~30 min):**
       - Overview
       - Player Fantasy
       - Core Rules (basic structure)

       **Session 2 (tomorrow):**
       - Formulas
       - Edge Cases
       - Dependencies

       **Session 3 (when ready):**
       - Tuning Knobs
       - Acceptance Criteria

       Does this work?"

User: "Yes, let's do Session 1 sections today"

Agent: [Works through Overview, Player Fantasy, Core Rules with Q&A]

Agent: "Session 1 sections complete. Should I:
       A) Save this as a WIP document with sections 4-8 marked as TODO
       B) Wait and only write the file when all sections are done
       C) Something else?"

User: "A - save it as WIP so I can review tonight"

Agent: "I'll create design/gdd/inventory-system.md with WIP markers:

       [Shows draft with this structure]

       ---
       # Inventory System (WIP)

       **Status:** INCOMPLETE - Sections 1-3 complete, 4-8 pending
       **Last Updated:** 2026-02-13
       **Next Session:** Complete Formulas and Edge Cases

       ## 1. Overview
       [Complete content]

       ## 2. Player Fantasy
       [Complete content]

       ## 3. Detailed Rules
       [Complete content]

       ## 4. Formulas
       **TODO:** Define capacity formulas, stack size calculations, weight calculations

       ## 5. Edge Cases
       **TODO:** Full inventory, item pickup while full, stack splitting behavior

       ## 6. Dependencies
       **TODO:** List integration points

       ## 7. Tuning Knobs
       **TODO:** List designer-facing values

       ## 8. Acceptance Criteria
       **TODO:** How to validate this works

       ---

       May I write this WIP document to design/gdd/inventory-system.md?"

User: "Yes"

Agent: [Writes file with WIP status clearly marked]

---

Session 2: Resume Work

User: "Let's continue the inventory GDD from yesterday"

Agent: "I'll read the current state of design/gdd/inventory-system.md...

       [Reads file]

       Current status:
       ✓ Section 1-3: Complete
       ⏸ Section 4-8: Pending

       Today we're tackling Formulas and Edge Cases. Before we start, any
       changes to sections 1-3 based on your review last night?"

User: "Actually, change the grid size from 8x6 to 10x8 in section 3"

Agent: [Updates section 3]

       "Updated. Now let's continue with Formulas. For capacity calculation,
       I need to know: Should it be based on weight, slot count, or both?"

[Agent works through sections 4-5 with same collaborative process]

Agent: "Sections 4-5 complete. Should I:
       A) Update the WIP doc with 1-5 complete, 6-8 pending
       B) Continue to sections 6-8 now
       C) Stop here and finish later?"

User: "A - update the WIP. I'll finish 6-8 tomorrow."

Agent: [Updates doc, changes status to "Sections 1-5 complete, 6-8 pending"]

---

Session 3: Finalize Document

User: "Let's finish the inventory GDD"

Agent: [Reads current WIP state]

       "Current status:
       ✓ Sections 1-5: Complete
       ⏸ Sections 6-8: Pending

       Finishing up with Dependencies, Tuning Knobs, Acceptance Criteria..."

[Agent completes final sections]

Agent: "All 8 sections complete! Should I:
       A) Remove WIP markers and mark as FINAL
       B) Run /design-review first to validate
       C) Keep as WIP for one more review cycle?"

User: "B - review it first"

Agent: [Runs /design-review design/gdd/inventory-system.md]

       "Design review passed! All 8 sections present and complete.
       Should I remove WIP markers now?"

User: "Yes"

Agent: [Updates doc, removes WIP status, marks as complete with final date]

       "Document finalized: design/gdd/inventory-system.md
       Status: COMPLETE
       Completed: 2026-02-15"

---

🏗️ WIP Document Structure

When saving incomplete documents, ALWAYS include:

# [System Name] (WIP)

**Status:** INCOMPLETE - Sections [X-Y] complete, [Z-W] pending
**Last Updated:** [Date]
**Last Session Summary:** [What was accomplished]
**Next Session Plan:** [What to work on next]

---

## Completed Sections

[Sections with full content]

---

## Pending Sections

[Sections with TODO markers explaining what's needed]

## 4. Formulas
**TODO:** [Specific guidance on what to address]
- Capacity calculation formula
- Stack size limits
- Weight-based restrictions

## 5. Edge Cases
**TODO:** Address these scenarios:
- Full inventory behavior
- Partial stack pickup
- Item swapping logic

---

📌 WIP Markers Reference

Use these status markers in documents:

**Status:** INCOMPLETE - Section 3 partial, 4-8 pending
**Status:** IN REVIEW - All sections complete, awaiting feedback
**Status:** COMPLETE - All sections finalized and reviewed
**Status:** DEPRECATED - Replaced by [new doc]

For sections:

## 4. Formulas
**STATUS: COMPLETE** - Reviewed 2026-02-13

## 5. Edge Cases
**STATUS: DRAFT** - Needs review

## 6. Dependencies
**STATUS: TODO** - Not started

## 7. Tuning Knobs
**STATUS: BLOCKED** - Waiting for systems-designer input on balance values

---

🔄 Git Workflow for WIP Docs

Committing WIP Work:

git add design/gdd/inventory-system.md
git commit -m "WIP: Inventory GDD sections 1-3 complete

Completed:
- Overview: Grid-based inventory (10x8)
- Player Fantasy: Spatial puzzle + organization
- Detailed Rules: Core pickup, drop, stack, swap logic

Pending:
- Formulas (session 2)
- Edge cases (session 2)
- Dependencies, Tuning, Acceptance (session 3)

per design/pillars.md Pillar 3"

Why commit WIP work?

• Preserves progress if you need to /clear context
• Allows review by others
• You can revert if you change direction

---

🎯 Best Practices

✅ DO:

• Mark WIP status clearly at the top of the doc
• Commit WIP versions so progress isn't lost
• Document what's done and what's pending explicitly
• Provide context for the next session (what to address)
• Update status as you progress (INCOMPLETE → IN REVIEW → COMPLETE)
• Use TODO with specifics ("TODO: Define edge case for X" not just "TODO")

❌ DON'T:

• Don't leave TODO sections blank - always explain what needs to be addressed
• Don't assume incomplete = bad - WIP is normal for complex systems
• Don't skip WIP markers - future-you needs to know what's finished
• Don't mix WIP and COMPLETE status without clear section markers
• Don't run /design-review on WIP docs - it will fail (intentionally, not all 8 sections complete)

---

🧩 Multi-Document Systems

Sometimes one "system" spans multiple documents:

Inventory System (umbrella concept):
├── design/gdd/inventory-grid.md (COMPLETE)
├── design/gdd/item-types.md (WIP - 60% done)
├── design/gdd/equipment-slots.md (TODO - not started)
└── design/gdd/inventory-ui.md (BLOCKED - waiting for ux-designer)

How to manage:

1. Create a tracker doc in design/gdd/inventory-system-TRACKER.md
2. List all sub-documents with status
3. Update tracker as each doc completes
4. When all complete, the "system" is complete

Example Tracker:

# Inventory System - Document Tracker

**Overall Status:** 60% Complete

| Document | Status | Owner | Blocker |
|----------|--------|-------|---------|
| inventory-grid.md | ✅ COMPLETE | game-designer | None |
| item-types.md | 🔄 WIP (60%) | systems-designer | Needs formula review |
| equipment-slots.md | ⏸ TODO | game-designer | Waiting for inventory-grid finalization |
| inventory-ui.md | 🚫 BLOCKED | ux-designer | Needs wireframes |

**Next Steps:**
1. Complete item-types formulas (systems-designer consultation)
2. Get ux-designer wireframes for UI doc
3. Start equipment-slots once grid is implemented

---

💡 Example: Large Inventory System Across 3 Sessions

Session 1 (30 min):

User: "Start inventory GDD, do first 3 sections"
Agent: [Creates sections 1-3]
Agent: "May I save as WIP with sections 4-8 pending?"
User: "Yes"
Result: design/gdd/inventory-system.md (WIP, 3/8 sections)

Session 2 (45 min):

User: "Continue inventory GDD"
Agent: [Reads WIP, completes sections 4-6]
Agent: "Sections 1-6 done. Continue to 7-8 or stop?"
User: "Stop here, I need to think about acceptance criteria"
Agent: "Updating WIP doc..."
Result: design/gdd/inventory-system.md (WIP, 6/8 sections)

Session 3 (20 min):

User: "Finish the inventory GDD"
Agent: [Reads WIP, completes sections 7-8]
Agent: "All sections complete. Run /design-review?"
User: "Yes"
Agent: [Review passes]
Agent: "Removing WIP markers, marking as COMPLETE"
Result: design/gdd/inventory-system.md (COMPLETE, 8/8 sections)

Total time: ~95 minutes across 3 days Result: High-quality, reviewed GDD without rushing

---

🚀 Key Takeaway

You DON'T have to finish documents in one session!

• Save WIP versions with clear markers
• Resume across multiple sessions
• Keep progress tracked and visible
• Commit WIP work to preserve it
• Agents support incremental workflows

The collaborative protocol works within sessions AND across sessions.