firefrost-operations-manual/docs/standards/FFG-STD-002-task-documentation.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: 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:

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

---

⚡ 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

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

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

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

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