firefrost-operations-manual/docs/standards/task-documentation-standard.md

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: 1.0
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:

# 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

### [#]. [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

# Add high-level entry in tasks.md following template above

Step 2: Create task directory

mkdir -p docs/tasks/[task-name]
cd docs/tasks/[task-name]

Step 3: Create README.md

# Use README template (see above)
# Include quick links, overview, doc list

Step 4: Create supporting docs as needed

# deployment-plan.md (if building something)
# usage-guide.md (if creating a tool)
# troubleshooting.md (if operational complexity)
# etc.

Step 5: Commit to Git

git add docs/tasks/[task-name]/
git commit -m "Add [task-name] documentation"
git push

Updating an Existing Task

Update in task directory:

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

# Update README.md status to "DEPLOYED" or "COMPLETE"
# Add completion date
# Add "completed by" attribution

Step 2: Update tasks.md

### [#]. [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

## ✅ COMPLETED TASKS

### [Task Name]
[Keep the completed entry for reference]

---

📚 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)

# [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

# Top-level heading (document title)
## Major sections
### Sub-sections
#### Details (use sparingly)

Code Blocks

# 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:

### 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:

### 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

# [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

# 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:

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 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