From 052fc71433da37e3240dfee761dd33daa9f28e07 Mon Sep 17 00:00:00 2001
From: Michael Krause <mkrause612@gmail.com>
Date: Mon, 9 Feb 2026 12:18:30 -0600
Subject: [PATCH] Add documentation maintenance protocol to workflow guide

Established core principle: 'Always revise ALL documents when changes occur'

Documented:
- Why documentation drift is harmful
- What triggers updates (pivots, deployments, decisions)
- Which documents to check (scope, handoff, memory, instructions)
- The 4-step update workflow
- Examples of good discipline
- Anti-patterns to avoid
- The 5-minute rule

Prevents: Technical debt, context loss, future confusion
Ensures: Fast session starts, clear audit trail, team collaboration
---
 docs/workflow-guide.md | 127 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/docs/workflow-guide.md b/docs/workflow-guide.md
index 7b0e4b7..6f0b3af 100644
--- a/docs/workflow-guide.md
+++ b/docs/workflow-guide.md
@@ -778,3 +778,130 @@ This includes:
 
 **Fire + Frost = Where Passion Meets Precision** 🔥❄️
 
+
+---
+
+## Documentation Maintenance Protocol
+
+**Core Principle:** *"Always revise ALL documents when changes occur"*
+
+### Why This Matters
+
+**The Documentation Drift Problem:**
+- Project files get stale → Future Claude sessions get wrong context
+- Memory becomes outdated → Contradictions emerge
+- Session handoff falls behind → Time wasted catching up
+- Technical decisions get lost → "I thought we documented that?"
+
+**The Solution:**
+When ANY significant change occurs, update ALL affected documents in the same session.
+
+### What Triggers Documentation Updates
+
+**ALWAYS update when:**
+1. Architecture pivot (e.g., BookStack → MkDocs)
+2. New system deployed (e.g., automation framework)
+3. Phase completion or status change
+4. Major technical decision made
+5. Process change identified
+
+**Documents to Check:**
+- ✅ FIREFROST-PROJECT-SCOPE-V2.md (master document)
+- ✅ session-handoff.md (current status)
+- ✅ Project memory (via Claude interface)
+- ✅ Project instructions (if workflow changes)
+- ✅ Deployment guides (if applicable)
+
+### The Update Workflow
+
+**Step 1: Identify Impact**
+- What changed?
+- Which documents reference this?
+- What will future Claude need to know?
+
+**Step 2: Update Documents**
+- Master scope (if architecture/phase/goals change)
+- Session handoff (if current state changes)
+- Deployment guides (if technical details change)
+- Memory/instructions (if process changes)
+
+**Step 3: Commit Everything**
+- Single commit with all related updates
+- Clear commit message explaining the change
+- Push to Git immediately
+
+**Step 4: Verify**
+- Quickly review updated docs for consistency
+- Check that future Claude will have correct context
+
+### Examples of Good Documentation Discipline
+
+**Example 1: Automation System Deployed**
+- ✅ Added to Project Scope (Infrastructure section)
+- ✅ Updated session-handoff (Current State)
+- ✅ Updated memory (Tools & Resources)
+- ✅ Updated instructions (Automation First)
+- ✅ Created USAGE.md guide
+- Result: Future Claude knows to use automation
+
+**Example 2: BookStack → MkDocs Pivot**
+- ✅ Updated Project Scope (Three-tier architecture)
+- ✅ Archived old plans
+- ✅ Created new deployment guide
+- ✅ Updated timeline
+- Result: No confusion about which system we're using
+
+**Example 3: Phase 1 DDoS Gap Identified**
+- ✅ Added Phase 1 section to Project Scope
+- ✅ Documented decision to revise when gaps found
+- Result: Complete picture of all phases
+
+### Anti-Patterns to Avoid
+
+**❌ "I'll document it later"**
+- Later never comes
+- Context is lost
+- Future sessions waste time reconstructing
+
+**❌ "It's in my head"**
+- Future Claude can't read your mind
+- Team members can't help
+- You'll forget details
+
+**❌ "Just one quick change"**
+- Leads to drift between docs
+- Causes contradictions
+- Breaks continuity
+
+### The 5-Minute Rule
+
+**If a change takes 5 minutes to implement, spend 5 minutes documenting it.**
+
+This includes:
+- Updating master scope
+- Quick note in session handoff
+- Git commit message with context
+
+**Investment:** 10 minutes total  
+**Payoff:** Hours saved in future sessions
+
+### Success Metrics
+
+**Good Documentation Discipline:**
+- Future Claude sessions start fast (no 10-minute catchup)
+- No contradictions between documents
+- Clear audit trail of decisions
+- Team can contribute without confusion
+
+**Poor Documentation Discipline:**
+- "Wait, I thought we removed that?"
+- "What was the reason we chose X over Y?"
+- "Is this document current?"
+- Wasted time reconstructing context
+
+---
+
+**Remember:** Documentation is not separate from the work—it IS the work.
+
+**Fire + Frost = Where Passion Meets Precision** 🔥❄️
+