firefrost-gaming/firefrost-operations-manual

Files

Claude df3f5e3860 standards: Update FFG-STD-002 to v2.0 - Add Decision Capture Rule

Major additions to prevent documentation gaps:

1. Decision Capture Rule (CRITICAL)
   - Immediate documentation of all decisions (within 5 minutes)
   - Prevents 'verbal decision → lost context' failure mode
   - Real example: Reddit/Bluesky/Mastodon/Kick platform decision

2. Task Status Precision
   - New 6-status system: ✅ COMPLETE, 🔄 IN PROGRESS, ⏳ WAITING,
     📋 READY, ❌ BLOCKED, 🗓️ PLANNED
   - Required WHO/WHAT context for WAITING status
   - Examples of good vs bad documentation

Root cause addressed: NEXT-SESSION-PRIORITY.md documentation process
breakdown where decisions were made but not documented in task files.

Version: 1.0 → 2.0
Updated by: The Verifier (Chronicler #42)

2026-03-26 07:26:18 +00:00

26 KiB

Raw Blame History

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:

Michael makes a decision during a session (add platforms, change priority, assign to someone)
Chronicler remembers the decision in session context
Decision is NOT immediately documented in task files
Next Chronicler reads task files, decision is completely lost
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:

Update the relevant task documentation (tasks.md or task directory files)
Commit with message: docs: Update Task #XX - [decision]
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:

What/who we're waiting on (person, service, approval)
Current progress (if applicable: "2/11 done")
Velocity assessment (fast/slow/stalled)
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

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

26 KiB Raw Blame History