#!/bin/bash
# Add documentation maintenance principle to workflow guide

cd ~/firefrost-work/firefrost-operations-manual

# Append to workflow-guide.md
cat >> docs/workflow-guide.md << 'DOCEOF'

---

## 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** 🔥❄️

DOCEOF

# Commit
git add docs/workflow-guide.md
git commit -m "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"

git push

echo "Documentation maintenance protocol added to workflow guide"
