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:**
```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]
```

---

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