# Task Documentation Standard ## Firefrost Gaming Operations Manual **Document Status:** ACTIVE STANDARD **Created:** February 16, 2026 **Created By:** The Chronicler (current session) **Authority:** Michael "Frostystyle" Krause + The Chronicler **Version:** 2.0 (Updated March 26, 2026) **Applies To:** All tasks in `docs/core/tasks.md` --- ## 🎯 PURPOSE ### The Problem This Solves **Before this standard:** - Tasks.md became a 1000+ line mixed-detail document - Implementation details buried in master task list - Hard to find related documentation - Duplication across multiple files - Updates in one place didn't propagate - "Which version is authoritative?" confusion - Context muddying (high-level mixed with low-level) **After this standard:** - Tasks.md stays high-level (executive summary) - Each task gets its own directory for all related docs - Clear separation: planning vs implementation vs operations - Single source of truth per topic - Easy to find everything related to a task - Scalable (task can have 1 or 20 documents) --- ## 📁 DIRECTORY STRUCTURE ### Standard Layout ``` docs/ ├── core/ │ └── tasks.md # Master task list (high-level only) │ ├── tasks/ # One directory per major task │ ├── [task-name]/ │ │ ├── README.md # Task overview (required) │ │ ├── deployment-plan.md # How to deploy/build (if applicable) │ │ ├── usage-guide.md # How to use after deployed │ │ ├── troubleshooting.md # Common issues and solutions │ │ ├── maintenance.md # Ongoing operations │ │ ├── prerequisites.md # What's needed before starting │ │ ├── testing-checklist.md # Validation steps │ │ ├── config-examples/ # Sample configurations │ │ ├── scripts/ # Any automation scripts │ │ └── archive/ # Historical versions │ │ │ ├── whitelist-manager/ │ │ ├── README.md │ │ ├── deployment-plan.md │ │ ├── usage-guide.md │ │ └── troubleshooting.md │ │ │ ├── frostwall-protocol/ │ │ ├── README.md │ │ ├── deployment-plan.md │ │ ├── gre-tunnel-config.md │ │ ├── ufw-rules.md │ │ └── recovery-procedures.md │ │ │ └── mailcow-email/ │ ├── README.md │ ├── deployment-plan.md │ ├── dns-configuration.md │ └── ssl-setup.md ``` --- ## 📝 TASK DIRECTORY REQUIREMENTS ### Required Files (Every Task) **1. README.md** - Task overview and purpose - Quick reference links to other docs in directory - Status (planning, in-progress, deployed, deprecated) - Owner/responsibility - Last updated date **Example:** ```markdown # Whitelist Manager Web Dashboard **Status:** Planning **Owner:** Michael "Frostystyle" Krause **Priority:** Tier 0 - Immediate Win **Last Updated:** 2026-02-16 ## Quick Links - [Deployment Plan](deployment-plan.md) - Full build guide - [Usage Guide](usage-guide.md) - How to use - [Troubleshooting](troubleshooting.md) - Common issues ## Overview Web dashboard for managing Minecraft server whitelists... ## Documentation in This Directory - `deployment-plan.md` - Complete 6-phase deployment - `usage-guide.md` - Staff usage instructions - `troubleshooting.md` - Error recovery ``` ### Optional Files (As Needed) **deployment-plan.md** - For infrastructure/build tasks - Complete step-by-step deployment - Prerequisites checklist - Phase breakdown with time estimates - Code examples - Testing procedures - Rollback procedures **usage-guide.md** - For tools/services after deployment - How staff use the tool - Common workflows - Screenshots/examples - Access control **troubleshooting.md** - For operational tasks - Common issues - Error messages and solutions - Recovery procedures - Emergency contacts **maintenance.md** - For ongoing operations - Daily/weekly/monthly tasks - Update procedures - Backup procedures - Health checks **prerequisites.md** - For complex deployments - Required access/credentials - Dependencies - System requirements - Pre-flight checklist **testing-checklist.md** - For quality assurance - Test scenarios - Validation steps - Success criteria - Regression tests --- ## 📋 TASKS.MD FORMAT ### High-Level Entry Only **What belongs in tasks.md:** - ✅ Task number and name - ✅ Time estimate - ✅ Priority/tier - ✅ Status (ready/blocked/in-progress/complete) - ✅ **Reference to task directory** - ✅ 2-3 sentence overview - ✅ Key deliverables (bullet points) - ✅ Dependencies (what blocks this) - ✅ Quick summary of value/outcome **What does NOT belong in tasks.md:** - ❌ Step-by-step instructions - ❌ Code examples - ❌ Configuration details - ❌ Troubleshooting guides - ❌ Full deployment procedures - ❌ Anything longer than 1 screen ### Template ```markdown ### [#]. [Task Name] **Time:** [X hours] **Status:** [READY/BLOCKED/IN-PROGRESS/COMPLETE] **Priority:** [Tier X - Description] **Documentation:** `docs/tasks/[task-name]/` **Overview:** [2-3 sentence description of what this task accomplishes] **Key Deliverables:** - [Deliverable 1] - [Deliverable 2] - [Deliverable 3] **Dependencies:** - Blocks: [Tasks that need this done first] - Blocked by: [Tasks that must complete before this] **Value:** [One sentence on why this matters] **Quick Reference:** - `README.md` - Task overview - `deployment-plan.md` - Build guide - `usage-guide.md` - How to use **See task directory for complete documentation.** ``` --- ## 🔄 WORKFLOW ### Creating a New Task **Step 1: Add to tasks.md** ```bash # Add high-level entry in tasks.md following template above ``` **Step 2: Create task directory** ```bash mkdir -p docs/tasks/[task-name] cd docs/tasks/[task-name] ``` **Step 3: Create README.md** ```bash # Use README template (see above) # Include quick links, overview, doc list ``` **Step 4: Create supporting docs as needed** ```bash # deployment-plan.md (if building something) # usage-guide.md (if creating a tool) # troubleshooting.md (if operational complexity) # etc. ``` **Step 5: Commit to Git** ```bash git add docs/tasks/[task-name]/ git commit -m "Add [task-name] documentation" git push ``` ### Updating an Existing Task **Update in task directory:** ```bash cd docs/tasks/[task-name] # Edit relevant .md files git commit -m "Update [task-name]: [what changed]" ``` **Update tasks.md only if:** - Status changes (ready → in-progress → complete) - Time estimate significantly changes - Priority/tier changes - High-level scope changes **DO NOT update tasks.md for:** - Implementation detail changes - New troubleshooting steps - Updated configurations - Minor clarifications ### Completing a Task **Step 1: Mark complete in task directory** ```bash # Update README.md status to "DEPLOYED" or "COMPLETE" # Add completion date # Add "completed by" attribution ``` **Step 2: Update tasks.md** ```markdown ### [#]. [Task Name] — ✅ COMPLETE **Completed:** [Date] **Completed By:** [Person/Chronicler] **Documentation:** `docs/tasks/[task-name]/` [Brief summary of outcome] **See task directory for complete documentation.** ``` **Step 3: Move to completed section** ```markdown ## ✅ COMPLETED TASKS ### [Task Name] [Keep the completed entry for reference] ``` --- ## ⚡ DECISION CAPTURE RULE (CRITICAL) ### The Problem: Verbal Decision → Lost Context **What happens:** 1. Michael makes a decision during a session (add platforms, change priority, assign to someone) 2. Chronicler remembers the decision in session context 3. Decision is NOT immediately documented in task files 4. Next Chronicler reads task files, decision is completely lost 5. Work gets marked "supposed to be done" but has no documentation **Real example (March 2026):** - Decision: Add Reddit, Bluesky, Mastodon, Kick to social media platforms - NOT documented in Task #56 - Next Chronicler had no idea these platforms were decided - Created documentation gap that looked like failed work ### The Rule: Immediate Documentation **WHENEVER Michael makes a decision that affects a task, the Chronicler MUST:** **Within 5 minutes:** 1. Update the relevant task documentation (tasks.md or task directory files) 2. Commit with message: `docs: Update Task #XX - [decision]` 3. Push to Gitea before continuing other work **Examples of decisions requiring immediate documentation:** - ✅ Adding items to a list (platforms, features, requirements) - ✅ Changing task priority or status - ✅ Assigning task to someone (Meg, Holly, team member) - ✅ Setting deadlines or dependencies - ✅ Deciding to defer or cancel work - ✅ Changing scope (add/remove deliverables) - ✅ Resource allocation decisions **This applies even for "small" decisions** - if it changes what's documented, document it NOW. ### Why This Is Non-Negotiable **Without immediate documentation:** - Next Chronicler has no record of the decision - Handoffs become "he said / she said" - Work gets duplicated or missed entirely - Context slowly degrades across sessions **With immediate documentation:** - All Chroniclers work from same source of truth - Decisions are traceable (Git history shows when/why) - No "supposed to be done" confusion - Clean handoffs between sessions ### Workflow Example ```bash # Michael says: "Add Reddit to the social media platform list" # IMMEDIATELY (before continuing conversation): cd /home/claude/firefrost-operations-manual vim docs/core/tasks.md # Add Reddit to Task #56 platform list git add docs/core/tasks.md git commit -m "docs: Update Task #56 - Add Reddit to platform list Decision made during session with Michael (2026-03-26). Expands social media presence from 10 to 11 platforms." git push # THEN continue with other work ``` **Time cost:** 2-3 minutes per decision **Value:** Prevents hours of confusion and rework ### Exception: Exploratory Discussions **NOT every conversation requires documentation:** - ❌ "What if we..." brainstorming (no decision made) - ❌ "How would X work?" technical questions (no commitment) - ❌ "Maybe someday..." future possibilities (not actionable) **Only DECISIONS require immediate documentation:** - ✅ "Yes, add that platform" (decision made) - ✅ "Assign this to Meg" (decision made) - ✅ "This is now high priority" (decision made) **When in doubt:** Ask Michael: "Should I document this decision now?" --- ## 📊 TASK STATUS PRECISION ### The Problem: Vague Status Labels **Current status labels are ambiguous:** - "READY" - Ready to start? Prerequisites ready? Ready to finish? - "PENDING" - Pending what? Who? When? - "BLOCKED" - Blocked by what specifically? This creates handoff confusion where next Chronicler doesn't know actual state. ### New Status System **Use these precise status indicators:** **✅ COMPLETE** - Work is done and verified - Deliverables deployed and tested - Documentation updated - Include completion date **🔄 IN PROGRESS** - Active work happening this session - Clear who is working on it - Expected completion timeframe noted **⏳ WAITING - [Specific Dependency]** - Blocked by external dependency - **MUST document WHO or WHAT we're waiting on** - Examples: - `⏳ WAITING - Meg creating accounts (2/11 done, slow progress)` - `⏳ WAITING - Breezehost unblocking port 25` - `⏳ WAITING - Holly reviewing build design` **📋 READY** - All prerequisites met - Can start immediately - No blockers or dependencies **❌ BLOCKED - [Specific Blocker]** - Cannot proceed - **MUST document what's blocking** - Examples: - `❌ BLOCKED - Task #38 (security update) must complete first` - `❌ BLOCKED - API credentials not yet created` **🗓️ PLANNED** - Future work - Not yet ready to start - Prerequisites not met ### Required Context for WAITING Status **NEVER use just "WAITING"** - always include: 1. **What/who we're waiting on** (person, service, approval) 2. **Current progress** (if applicable: "2/11 done") 3. **Velocity assessment** (fast/slow/stalled) 4. **Critical path impact** (does this block soft launch?) **Example - Good:** ```markdown **Status:** ⏳ WAITING - External dependency **Assigned:** Meg (community manager) **Progress:** 2/11 platforms complete (Discord, Facebook done) **Velocity:** Slow (accounts created on Meg's timeline) **Critical Path:** Not blocking soft launch (footer shows "Coming Soon") ``` **Example - Bad:** ```markdown **Status:** PENDING ``` ### Why This Matters **Precise status enables:** - ✅ Next Chronicler knows exact state without asking - ✅ Can assess critical path impact immediately - ✅ Knows who to follow up with - ✅ Understands timeline expectations - ✅ No "supposed to be done" confusion **Vague status creates:** - ❌ "What does READY mean here?" - ❌ "Who do I ask about this?" - ❌ "Is this blocking anything?" - ❌ Wasted time hunting for context ### Migration Note Existing tasks will be updated to new status system as they're touched. New tasks MUST use precise status from creation. --- ## 📚 NAMING CONVENTIONS ### Directory Names - **Format:** `[descriptive-name]` (lowercase, hyphens) - **Examples:** - `whitelist-manager` - `frostwall-protocol` - `mailcow-email` - `ai-stack-deployment` - `terraria-branding-training` ### File Names - **Format:** `[purpose].md` (lowercase, hyphens) - **Standard names:** - `README.md` (always capitalized) - `deployment-plan.md` - `usage-guide.md` - `troubleshooting.md` - `maintenance.md` - `prerequisites.md` - `testing-checklist.md` ### Avoid - ❌ Spaces in names - ❌ Special characters - ❌ ALL_CAPS (except README.md) - ❌ Version numbers in filenames (use Git history) - ❌ Dates in filenames (use Git history) --- ## 🎨 DOCUMENT FORMATTING ### Standard Header (All Task Docs) ```markdown # [Document Title] **Task:** [Task Name] **Document Type:** [deployment-plan/usage-guide/troubleshooting/etc] **Status:** [DRAFT/ACTIVE/DEPRECATED] **Last Updated:** [YYYY-MM-DD] **Owner:** [Person responsible] --- [Document content...] ``` ### Section Hierarchy ```markdown # Top-level heading (document title) ## Major sections ### Sub-sections #### Details (use sparingly) ``` ### Code Blocks ```markdown # Always specify language ```bash # Good command --flag value ``` # Not this ``` command --flag value ``` ``` ### File Paths ```markdown # Use backticks for paths Configuration file: `docs/tasks/example/config.json` # Use code blocks for file contents **File:** `config.json` ```json { "key": "value" } ``` ``` --- ## ✅ MIGRATION STRATEGY ### For Existing Tasks **Phase 1: New Standard (Now)** - ✅ Document created - ✅ Standard established - ✅ All new tasks follow this pattern **Phase 2: Gradual Migration (Ongoing)** - When touching an existing task, migrate its docs - No rush, no breaking changes - Natural evolution over time **Phase 3: Complete Migration (Future)** - All tasks have dedicated directories - Tasks.md is purely high-level - Complete consistency ### Migration Checklist (Per Task) When migrating an existing task: - [ ] Create `docs/tasks/[task-name]/` directory - [ ] Create `README.md` in task directory - [ ] Move/create relevant docs: - [ ] deployment-plan.md (if exists) - [ ] usage-guide.md (if needed) - [ ] troubleshooting.md (if needed) - [ ] Update tasks.md to reference new directory - [ ] Update any links in other docs - [ ] Test all links work - [ ] Commit changes - [ ] Delete old scattered docs (after confirming migration complete) --- ## 🔍 EXAMPLES ### Example 1: Simple Task (Command Center Cleanup) **Directory:** ``` docs/tasks/command-center-cleanup/ ├── README.md # Overview └── procedure.md # Step-by-step cleanup ``` **tasks.md entry:** ```markdown ### 2. Command Center Root Cleanup **Time:** 15 minutes **Status:** READY **Documentation:** `docs/tasks/command-center-cleanup/` **Overview:** Housekeeping - move Gitea backups, archive logs, delete cruft. **See task directory for cleanup procedure.** ``` --- ### Example 2: Complex Infrastructure Task (Frostwall) **Directory:** ``` docs/tasks/frostwall-protocol/ ├── README.md # Overview ├── deployment-plan.md # Full deployment ├── gre-tunnel-configuration.md # GRE setup ├── nat-dmz-configuration.md # NAT/DMZ setup ├── ufw-rules.md # Firewall rules ├── ip-hierarchy.md # IP allocation ├── testing-checklist.md # Validation ├── troubleshooting.md # Recovery ├── maintenance.md # Ongoing ops └── config-examples/ ├── gre-tunnel-tx1.conf ├── gre-tunnel-nc1.conf └── ufw-rules-example.sh ``` **tasks.md entry:** ```markdown ### 5. The Frostwall Protocol — GRE Tunnel Security **Time:** 3-4 hours **Status:** READY **Priority:** CRITICAL **Documentation:** `docs/tasks/frostwall-protocol/` **Overview:** DDoS protection using GRE tunnels from Command Center to remote nodes. Hides real server IPs, protects all game traffic. **Key Deliverables:** - GRE tunnels: Command Center ↔ TX1, NC1 - 1-to-1 NAT/DMZ with /29 IP block - Iron Wall UFW rules - Self-healing persistence **Dependencies:** - Blocks: Mailcow, AI Stack, all Tier 2+ work - Blocked by: None (foundational) **Quick Reference:** - `deployment-plan.md` - Complete build guide - `gre-tunnel-configuration.md` - Tunnel setup - `troubleshooting.md` - Recovery procedures **See task directory for complete documentation.** ``` --- ### Example 3: Service Deployment (Whitelist Manager) **Directory:** ``` docs/tasks/whitelist-manager/ ├── README.md # Overview ├── deployment-plan.md # 6-phase deployment ├── prerequisites.md # What's needed ├── usage-guide.md # How staff use it ├── troubleshooting.md # Common issues ├── maintenance.md # Ongoing ops └── config-examples/ ├── config.json.example └── nginx-example.conf ``` **tasks.md entry:** ```markdown ### 1. Centralized Whitelist Manager Web Dashboard **Time:** 2-2.5 hours **Status:** READY TO BUILD **Documentation:** `docs/tasks/whitelist-manager/` **Overview:** Build web dashboard at whitelist.firefrostgaming.com to manage player whitelists across 11 Minecraft servers. **Key Deliverables:** - Web interface with server list - Toggle whitelist ON/OFF per server - Add/remove players (individual or bulk) - Staff authentication **Value:** 15-minute manual task → 30 seconds **Quick Reference:** - `deployment-plan.md` - Complete 6-phase guide - `prerequisites.md` - API keys, credentials needed - `usage-guide.md` - How to use after deployed **See task directory for complete documentation.** ``` --- ## 🚀 BENEFITS ### For Task Execution - ✅ All related docs in one place - ✅ Clear what exists vs what's missing - ✅ Easy to find "how do I...?" - ✅ Self-contained (task directory is portable) ### For Maintenance - ✅ Update one place, not scattered files - ✅ Version control per task directory - ✅ Easy to deprecate old approaches - ✅ Clear documentation audit trail ### For Collaboration - ✅ New Chroniclers know where to look - ✅ Staff can find usage guides - ✅ Meg can reference without digging - ✅ Future children see complete context ### For Scaling - ✅ Task can grow from 1 to 20 docs without cluttering - ✅ Tasks.md stays readable as we hit 50+ tasks - ✅ Easy to archive completed task directories - ✅ Pattern proven, repeatable --- ## 📏 QUALITY STANDARDS ### Documentation Must Be: **1. Discoverable** - Task directory name is obvious - README.md provides clear navigation - Links work and are maintained **2. Complete** - All promised docs exist - No "TODO" placeholders older than 1 week - Every procedure has success criteria **3. Tested** - Procedures verified before documenting - Code examples actually work - Links confirmed valid **4. Maintained** - Last updated date is accurate - Deprecated docs marked clearly - Changes propagate to dependent docs **5. Accessible** - Written for The Chronicler AND staff - Technical jargon explained - Assumes reader hasn't seen other docs ### Review Checklist Before marking task docs complete: - [ ] README.md exists and is current - [ ] All referenced docs exist - [ ] All links work - [ ] Code examples tested - [ ] Procedures include success criteria - [ ] Screenshots/diagrams added if helpful - [ ] Last updated date is current - [ ] Committed to Git - [ ] Referenced correctly in tasks.md --- ## 🔄 DOCUMENT LIFECYCLE ### States **DRAFT** - Being written, not yet ready for use **ACTIVE** - Current, tested, use this version **DEPRECATED** - Old approach, kept for reference **ARCHIVED** - Historical, moved to archive/ subdirectory ### Transitions ``` DRAFT → ACTIVE When: Tested and verified Action: Update status header ACTIVE → DEPRECATED When: Better approach exists Action: Add deprecation notice, link to new doc DEPRECATED → ARCHIVED When: No longer referenced Action: Move to archive/ subdirectory ``` ### Deprecation Notice Template ```markdown # [Document Title] > ⚠️ **DEPRECATED:** This document describes an old approach. > > **New approach:** See [new-approach.md](new-approach.md) > **Deprecated on:** 2026-03-15 > **Reason:** [Why this was replaced] > > This document is kept for historical reference only. --- [Original content preserved below...] ``` --- ## 💡 TIPS & BEST PRACTICES ### Writing Task Documentation **Start with README.md** - Gives you structure - Identifies what docs you need - Prevents scope creep **One purpose per document** - deployment-plan.md ≠ usage-guide.md - Keep concerns separated - Easier to maintain **Code examples over prose** ```bash # Good: Show the actual command curl -X POST https://api.example.com/endpoint # Not this: "Use curl to POST to the API endpoint" ``` **Test everything you document** - Run every command - Follow every procedure - Verify every link - Screenshot actual results **Write for your future self** - You'll forget details - Document why, not just what - Include context for decisions - Link to related discussions ### Organizing Complex Tasks **Use subdirectories for categories:** ``` docs/tasks/frostwall-protocol/ ├── README.md ├── planning/ │ ├── architecture-decisions.md │ └── ip-allocation-plan.md ├── deployment/ │ ├── phase-1-gre-tunnels.md │ ├── phase-2-nat-config.md │ └── phase-3-ufw-rules.md └── operations/ ├── monitoring.md └── incident-response.md ``` **Break long procedures into phases:** - Phase 1: Prerequisites - Phase 2: Core deployment - Phase 3: Testing - Phase 4: Monitoring **Link between related docs:** ```markdown See also: - [GRE Tunnel Config](gre-tunnel-configuration.md) - [UFW Rules](ufw-rules.md) - [Troubleshooting](troubleshooting.md) ``` --- ## 🎯 ENFORCEMENT ### This Standard Applies To: ✅ **All new tasks** added to tasks.md ✅ **All major updates** to existing tasks ✅ **All infrastructure deployments** ✅ **All service configurations** ✅ **All operational procedures** ### Exceptions: **Quick wins (<30 min)** can be inline in tasks.md if: - Single document would be complete reference - No ongoing maintenance needed - Unlikely to expand in scope **Example:** Command Center Cleanup might stay inline, or get minimal directory. ### Responsible Parties: **The Chronicler:** - Maintains this standard - Creates task directories for new work - Migrates existing tasks when touched - Reviews documentation quality **Michael:** - Approves deviations from standard - Provides feedback on clarity - Tests procedures before deployment **Meg:** - Reviews usage guides for staff tools - Confirms documentation is accessible --- ## 📋 CHANGELOG ### Version 2.0 (2026-03-26) **Added by:** The Verifier (Chronicler #42) **Reason:** Documentation process breakdown (NEXT-SESSION-PRIORITY.md) **Major additions:** - ⚡ Decision Capture Rule (CRITICAL) - Immediate documentation of all decisions - 📊 Task Status Precision - New 6-status system with required context - Eliminated "verbal decision → lost context" failure mode - Required WHO/WHAT context for WAITING status - Examples of good vs bad status documentation **Impact:** Prevents documentation gaps between Chronicler sessions ### Version 1.0 (2026-02-16) - Initial standard created - Established directory structure - Defined file requirements - Created templates and examples - Set quality standards - Documented migration strategy **Created by:** The Chronicler (current session) **Approved by:** Michael "Frostystyle" Krause (implicit via Option B selection) --- ## 🔗 REFERENCES ### Related Standards - This is currently the only standard in `docs/standards/` - Future standards may include: - naming-conventions.md (extract from DOCUMENT-INDEX) - git-workflow.md (document commit conventions) - code-style.md (if needed for development work) **Note:** Examples below reference standards that don't exist yet. Treat as illustrative. ### Example Task Directories - `docs/tasks/whitelist-manager/` - ✅ IMPLEMENTED - First task using this standard (Feb 16, 2026) - `docs/tasks/frostwall-protocol/` - Example (when created) - Complex infrastructure task - `docs/tasks/mailcow-email/` - Example (when created) - Service deployment task **Note:** Only whitelist-manager currently exists. Other examples are illustrative of future tasks. ### Core Documents - `docs/core/tasks.md` - Master task list - `DOCUMENT-INDEX.md` - Repository file map - `README.md` - Repository overview --- **Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ **Standard Status:** ACTIVE **Applies From:** February 16, 2026 **Review Cycle:** Quarterly or as needed **Maintained By:** The Chronicler lineage