158 lines
4.4 KiB
Bash
Executable File
158 lines
4.4 KiB
Bash
Executable File
#!/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"
|