firefrost-operations-manual/docs/reference/implementation-guide-priority-improvements.md

Implementation Guide: Priority Documentation System Improvements

Firefrost Gaming Operations Manual

Based on: Documentation System Review (Feb 16, 2026)
Focus: High and Medium priority recommendations
Audience: Michael + Future Chroniclers implementing these changes

---

OVERVIEW

This guide provides step-by-step implementation details for the top 15 recommendations from the documentation review. Each improvement includes:

• Clear rationale (why this matters)
• Concrete deliverables (what to create)
• Step-by-step procedures (how to do it)
• Success criteria (how to know it's done)
• Estimated time investment

Total estimated time for all improvements: 8-12 hours spread over 4 weeks

---

IMMEDIATE PRIORITY (Week 1)

1. Standardize Status Terminology

Problem: Three different status vocabularies create confusion

• tasks.md uses: READY, BLOCKED, IN-PROGRESS, COMPLETE
• READMEs use: Planning, Deployed, Rebuild Pending, Ready
• Standard uses: DRAFT, ACTIVE, DEPRECATED, ARCHIVED

Solution: Adopt ONE vocabulary everywhere

Time: 1-2 hours

Recommended Vocabulary

Use tasks.md vocabulary (most visible to users):

Status	Meaning	Use When
PLANNING	Task being designed, not ready to execute	Creating task structure, gathering requirements
READY	All prerequisites met, can start immediately	Task has complete plan and no blockers
BLOCKED	Cannot proceed due to dependencies	Waiting on other tasks, access, or decisions
IN-PROGRESS	Currently being worked on	Active execution happening
COMPLETE	Finished and deployed/delivered	Task outcome achieved
ARCHIVED	Completed >30 days ago, moved to archive	Historical reference only

Document lifecycle states (for supporting docs):

• DRAFT - Document being written, not reviewed
• ACTIVE - Current, tested, use this version
• DEPRECATED - Superseded by newer approach
• ARCHIVED - Historical, moved to archive directory

Implementation Steps

Step 1: Update the Standard (15 min)

File: docs/standards/task-documentation-standard.md

Add new section after "Document Lifecycle":

## STATUS TERMINOLOGY

### Task Status (README.md, tasks.md)

Tasks use a 6-state lifecycle:

**PLANNING** - Task being designed
- Directory created, README started
- Requirements gathering
- Not ready for execution

**READY** - Ready to execute
- Complete deployment plan (if infrastructure)
- Prerequisites documented
- No blocking dependencies

**BLOCKED** - Waiting on dependencies
- External blockers (access, decisions, other tasks)
- Document what's blocking in README
- Specify unblock condition

**IN-PROGRESS** - Active work
- Currently being executed
- Update README with progress notes
- Commit work-in-progress docs

**COMPLETE** - Finished
- Outcome delivered/deployed
- Documentation verified against reality
- Completion date recorded

**ARCHIVED** - Historical
- Completed >30 days ago
- Moved to archive directory
- Kept for reference only

### Document Status (Supporting Docs)

Individual documents within a task directory use:

**DRAFT** - Being written, not reviewed
**ACTIVE** - Current, tested, canonical version
**DEPRECATED** - Superseded, kept for reference
**ARCHIVED** - Historical, in archive subdirectory

### Status Updates

**When to update:**
- README status changes when task state changes
- tasks.md updated to match README
- Document status changes when new version created

**Who updates:**
- Task owner updates README
- Chronicler updates tasks.md to match
- Both verify consistency

Step 2: Update All Task READMEs (30-45 min)

For each of 27 task directories:

# Script to help find status lines
for dir in docs/tasks/*/; do
  task=$(basename "$dir")
  status=$(grep "^\*\*Status:\*\*" "$dir/README.md" | head -1)
  echo "$task: $status"
done

Review output, update each README to use standard vocabulary:

# Before
**Status:** Planning  
**Status:** Rebuild Pending  
**Status:** Deployed  

# After  
**Status:** PLANNING  
**Status:** BLOCKED  
**Status:** COMPLETE  

Step 3: Update tasks.md (15 min)

Review all task entries in docs/core/tasks.md, ensure status matches README:

# Template
### [#]. [Task Name]
**Time:** [estimate]  
**Status:** [PLANNING|READY|BLOCKED|IN-PROGRESS|COMPLETE]  
**Documentation:** `docs/tasks/[task-name]/`

Step 4: Verify Consistency (10 min)

# Check for old terminology
grep -r "Status: Planning" docs/tasks/*/README.md
grep -r "Status: Deployed" docs/tasks/*/README.md
grep -r "Status: Rebuild Pending" docs/tasks/*/README.md

# Should return no results if migration complete

Success Criteria

• ✅ Standard document defines 6 task states clearly
• ✅ All 27 task READMEs use standard vocabulary
• ✅ tasks.md uses standard vocabulary
• ✅ No inconsistencies found in verification

Maintenance

Add to quality review checklist:

• New task READMEs must use standard status vocabulary
• Status updates must happen in both README and tasks.md

---

2. Create Task Creation Script

Problem: Creating new tasks requires manual copy-paste of README template, prone to inconsistency

Solution: Automated script to generate task structure

Time: 30 minutes

Implementation

File: automation/create-task.sh

#!/bin/bash
# create-task.sh - Generate new task directory and README
# Usage: ./create-task.sh

set -e

# Color output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

echo -e "${GREEN}=== Firefrost Task Creator ===${NC}\n"

# Get task information
read -p "Task name (lowercase-with-hyphens): " task_name
read -p "Task title (human-readable): " task_title
read -p "Owner (usually 'Michael \"Frostystyle\" Krause'): " owner
read -p "Priority (Tier 0-4 or 'CRITICAL'): " priority
read -p "Time estimate (e.g., '2-3 hours'): " time_est
read -p "Brief overview (one sentence): " overview

# Validate task name format
if [[ ! $task_name =~ ^[a-z0-9-]+$ ]]; then
  echo -e "${RED}ERROR: Task name must be lowercase letters, numbers, and hyphens only${NC}"
  echo "Got: $task_name"
  exit 1
fi

# Check if directory already exists
if [ -d "docs/tasks/$task_name" ]; then
  echo -e "${RED}ERROR: Task directory already exists: docs/tasks/$task_name${NC}"
  exit 1
fi

# Create directory
echo -e "\n${YELLOW}Creating directory...${NC}"
mkdir -p "docs/tasks/$task_name"

# Generate README
echo -e "${YELLOW}Generating README.md...${NC}"
cat > "docs/tasks/$task_name/README.md" <<EOF
# $task_title

**Status:** PLANNING  
**Owner:** $owner  
**Priority:** $priority  
**Last Updated:** $(date +%Y-%m-%d)  
**Time Estimate:** $time_est

---

## Overview

$overview

---

## What It Is

[Describe what this task accomplishes in detail]

---

## Success Criteria

- [ ] [Deliverable 1]
- [ ] [Deliverable 2]
- [ ] [Deliverable 3]

---

## Implementation Steps

1. **[Phase 1]**
   - [Step]
   - [Step]

2. **[Phase 2]**
   - [Step]
   - [Step]

---

## Blocks

**This task blocks:**
- [Task that depends on this]

**Blocked by:**
- [Task that must complete first]

---

## Documentation

**Current directory contents:**
- \`README.md\` - This file (task overview)

**Additional docs to create:**
- [ ] \`deployment-plan.md\` - If this is infrastructure/deployment task
- [ ] \`prerequisites.md\` - If complex prerequisites needed
- [ ] \`usage-guide.md\` - If this creates a tool/dashboard
- [ ] \`troubleshooting.md\` - If operational complexity expected

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️

---

**Document Status:** DRAFT  
**Next Steps:** Fill in overview, success criteria, and implementation steps
EOF

echo -e "${GREEN}✓ Created: docs/tasks/$task_name/README.md${NC}"

# Generate tasks.md entry template
echo -e "\n${YELLOW}Generating tasks.md entry...${NC}"
cat > "docs/tasks/$task_name/tasks-md-entry.txt" <<EOF
### [#]. $task_title
**Time:** $time_est  
**Status:** PLANNING  
**Documentation:** \`docs/tasks/$task_name/\`

$overview

**Key Deliverables:**
- [Deliverable 1]
- [Deliverable 2]

**Dependencies:**
- Blocks: [Tasks that need this done first]
- Blocked by: [Tasks that must complete before this]

**See task directory for complete documentation.**
EOF

echo -e "${GREEN}✓ Created: docs/tasks/$task_name/tasks-md-entry.txt${NC}"

# Summary
echo -e "\n${GREEN}=== Task Created Successfully ===${NC}"
echo -e "Directory: ${YELLOW}docs/tasks/$task_name/${NC}"
echo -e "\nNext steps:"
echo -e "1. Edit ${YELLOW}README.md${NC} - Fill in details"
echo -e "2. Copy entry from ${YELLOW}tasks-md-entry.txt${NC} into ${YELLOW}docs/core/tasks.md${NC}"
echo -e "3. Delete ${YELLOW}tasks-md-entry.txt${NC} after copying"
echo -e "4. Create additional docs as needed (deployment-plan.md, etc.)"
echo -e "5. Commit to Git: ${YELLOW}git add docs/tasks/$task_name/${NC}"
echo ""

Step 2: Make Executable

chmod +x automation/create-task.sh

Step 3: Test

cd /path/to/firefrost-operations-manual
./automation/create-task.sh

# Follow prompts to create test task
# Verify output looks correct
# Delete test task if satisfied

Step 4: Document Usage

Add to automation/USAGE.md:

## Creating New Tasks

Use the task creation script to generate task directory structure:

```bash
./automation/create-task.sh

The script will prompt for:

• Task name (lowercase-with-hyphens)
• Task title (human-readable)
• Owner (default: Michael)
• Priority (Tier 0-4)
• Time estimate
• Brief overview

Output:

• docs/tasks/[name]/README.md - Complete template
• docs/tasks/[name]/tasks-md-entry.txt - Entry to copy into tasks.md

After running:

1. Edit README.md to fill in details
2. Copy tasks-md-entry.txt content into docs/core/tasks.md
3. Delete tasks-md-entry.txt
4. Create additional docs as needed
5. Commit to Git

Validation:

• Task name must be lowercase, numbers, hyphens only
• Checks for existing directory (prevents overwrites)

#### Success Criteria

- ✅ Script exists and is executable
- ✅ Script generates valid README with all standard sections
- ✅ Script validates task name format
- ✅ Script prevents overwriting existing tasks
- ✅ Usage documented in automation/USAGE.md
- ✅ Tested with sample task creation

#### Benefits

- Reduces task creation time from 5-10 minutes to <1 minute
- Ensures consistency across all new tasks
- Prevents typos in standard sections
- Enforces naming conventions automatically

---

### 3. Migrate or Deprecate External Documentation

**Problem:** Some tasks reference external Google Docs as "current" documentation, creating confusion about authoritative source

**Solution:** For each external reference, either migrate content or explicitly mark external as canonical with verification date

**Time:** 2-3 hours

#### Implementation Strategy

**Decision Matrix:**

| If external doc is... | Action |
|----------------------|--------|
| Fully documented, ready to migrate | Migrate to task directory, mark Google Doc "ARCHIVED" |
| Outdated/incorrect (like Frostwall) | Mark as "DEPRECATED - Flawed Implementation", note in README |
| Actively maintained externally | Keep external as canonical, add "Last verified: DATE" |
| Shared with external collaborators | Keep external, note "External collaboration doc" |

#### Step-by-Step Process

**Step 1: Audit External References (20 min)**

```bash
# Find all external doc references
grep -r "http" docs/tasks/*/README.md | grep -i "google\|doc\|external"

# Expected output (example):
# docs/tasks/frostwall-protocol/README.md:https://docs.google.com/document/d/12Kh...

Create audit list:

# External Doc Audit - 2026-02-16

| Task | External URL | Type | Decision | Deadline |
|------|--------------|------|----------|----------|
| frostwall-protocol | Google Doc | Deployment guide (flawed) | Mark DEPRECATED | Feb 20 |
| [task-name] | [URL] | [Purpose] | [Action] | [Date] |

Step 2: For Each "Migrate" Decision

Example: Migrating a deployment guide

# 1. Open Google Doc in browser
# 2. Copy content to deployment-plan.md

cd docs/tasks/[task-name]

# 3. Create deployment-plan.md with migrated content
cat > deployment-plan.md <<EOF
# [Task Name] - Deployment Plan

**Document Status:** ACTIVE (migrated from Google Docs)  
**Original Source:** [Google Doc URL] (now archived)  
**Migrated:** $(date +%Y-%m-%d)  
**Last Updated:** $(date +%Y-%m-%d)

---

[PASTE MIGRATED CONTENT HERE]

---

**Migration Notes:**
- Content migrated from Google Docs on [date]
- Original doc marked as ARCHIVED
- This is now the canonical source
EOF

# 4. Update README to reference new location
# Change:
#   **Current:** Google Doc (external)
#   https://docs.google.com/...
#
# To:
#   **Documentation:** See deployment-plan.md in this directory

Step 3: For Each "Mark Deprecated" Decision

Example: Frostwall Protocol (incorrect implementation)

Update README.md:

## Documentation

**Current:** Repository documentation (when rebuild completes)  
**Status:** Awaiting rebuild with correct architecture

**Deprecated:** Google Doc (flawed implementation)  
https://docs.google.com/document/d/12Kh-AhUgJLOJrBgIjMiGi3xRZH1basRzv9Pa_-x1t_0/edit

> ⚠️ **Warning:** The Google Doc describes a previous implementation that was
> torn down due to architectural issues. Do not follow this guide.
> 
> **Reason for deprecation:** Incorrect GRE tunnel configuration
> **Deprecated on:** 2026-02-16
> **Correct approach:** Will be documented in deployment-plan.md upon rebuild

**Additional docs needed:**
- `deployment-plan.md` - Complete correct deployment (create during rebuild)
- `troubleshooting.md` - Recovery procedures
- `architecture-decisions.md` - Why previous approach failed

Step 4: For Each "Keep External" Decision

Example: Collaborative doc with external partner

## Documentation

**Primary Source:** Google Doc (external collaboration)  
https://docs.google.com/document/d/...  
**Last Verified:** 2026-02-16  
**Shared With:** Holly (Pokerole project)

> 📝 **Note:** This Google Doc is the canonical source because it's actively
> shared with external collaborators. Updates happen there first, then
> propagate to this repository.

**Verification Schedule:** Check monthly for updates
**Next Verification:** 2026-03-16

**Local Mirror:** `docs/external/[project-name]/`  
(Updated quarterly or when significant changes occur)

Step 5: Update Standard

Add to task-documentation-standard.md:

## EXTERNAL DOCUMENTATION POLICY

**Principle:** Repository should be self-contained when possible

**External docs are acceptable when:**
1. Actively shared with external collaborators
2. Maintained by third party (provider docs, API references)
3. Too large for Git (videos, large datasets)

**All external references must include:**
- URL
- Purpose/type of document
- "Last Verified" date
- Verification schedule (how often to check)
- Decision rationale (why external vs. migrated)

**Deprecated external docs must include:**
- Deprecation date
- Reason for deprecation
- Link to new canonical source (if migrated)
- Warning against following outdated info

**Template:**
```markdown
**External Documentation:** [URL]  
**Type:** [Purpose]  
**Last Verified:** [Date]  
**Verification Schedule:** [Frequency]  
**Rationale:** [Why external vs. migrated]

#### Success Criteria

- ✅ All external doc references audited and categorized
- ✅ Each reference has clear status (MIGRATED/DEPRECATED/EXTERNAL CANONICAL)
- ✅ No ambiguous "current: Google Doc" + "migration target" dual sources
- ✅ All external references include verification dates
- ✅ Policy added to standard document

---

### 4. Update DOCUMENT-INDEX.md

**Problem:** DOCUMENT-INDEX.md was created before FFG-STD-002, doesn't highlight new task directory pattern

**Solution:** Add section explaining task directory structure and navigation

**Time:** 20 minutes

#### Implementation

**File:** `DOCUMENT-INDEX.md`

**Add new section** after "📋 QUICK REFERENCE" section:

```markdown
### 📋 Task Planning & Execution
**Trigger:** "What tasks exist?", "How do I start task X?", "Where's the deployment plan for Y?"

- `docs/core/tasks.md` — Current task list (high-level summaries only, 10-15 lines per task)
- `docs/tasks/README.md` — Complete task index (one-line descriptions, grouped by category)
- `docs/tasks/[task-name]/` — Full documentation for each task
  - `README.md` — Task overview, status, what/why/how, navigation to other docs
  - `deployment-plan.md` — Step-by-step deployment (infrastructure tasks)
  - `usage-guide.md` — How to use after deployed (tools/dashboards)
  - `troubleshooting.md` — Common issues and recovery procedures
  - `prerequisites.md` — Requirements before starting
- `docs/standards/task-documentation-standard.md` — How task docs are organized (FFG-STD-002)

**Navigation pattern:**
1. Check `tasks.md` for current priorities and status
2. Go to task directory: `docs/tasks/[task-name]/`
3. Read `README.md` for overview
4. Follow links to specific docs (deployment-plan.md, etc.)

**Standard:** All tasks follow FFG-STD-002 (Task Documentation Standard)

Update the one-line summaries table:

Add:

| `tasks.md` | Current task list - high-level only, see task directories for details |
| `docs/tasks/[name]/README.md` | Task overview - what, why, status, links to detailed docs |
| `task-documentation-standard.md` | FFG-STD-002 - How all task docs are organized |

Update directory structure primer:

├── docs/
│   ├── core/          ← Critical living documents (updated frequently)
│   │   ├── tasks.md   ← Current task list (high-level only)
│   ├── tasks/         ← One directory per major task (all supporting docs)
│   │   ├── whitelist-manager/
│   │   │   ├── README.md           ← Task overview
│   │   │   ├── deployment-plan.md  ← Full deployment guide
│   │   │   └── prerequisites.md    ← Requirements checklist
│   │   ├── frostwall-protocol/
│   │   └── [27 other tasks]/
│   ├── standards/     ← Documentation standards
│   │   └── task-documentation-standard.md  ← FFG-STD-002

Success Criteria

• ✅ Task directory pattern explained in Quick Reference section
• ✅ Navigation workflow documented
• ✅ Directory structure primer shows task organization
• ✅ One-line summaries include key task docs

---

SHORT-TERM PRIORITY (Weeks 2-3)

5. Create Task Directory Index

Problem: No overview of what tasks exist without reading through status-heavy tasks.md

Solution: Create docs/tasks/README.md with categorized task list

Time: 1 hour

Implementation

File: docs/tasks/README.md

# Task Directory Index
**Firefrost Gaming Operations Manual**

**Last Updated:** [Auto-update on commit]  
**Total Tasks:** 27 active, 6 archived  
**Status:** See `docs/core/tasks.md` for current priorities

---

## How to Use This Index

This index lists all tasks by category. For each task:
- **Name** links to task directory
- **One-liner** describes what it is
- **Status** shows current state (see tasks.md for details)

**For task details:** See `docs/core/tasks.md` (priorities, dependencies, time estimates)  
**For task documentation:** See task directory README.md  
**For creating new tasks:** See `docs/standards/task-documentation-standard.md`

---

## Infrastructure (8 tasks)

Critical servers, networking, and core services.

| Task | Description | Status |
|------|-------------|--------|
| [frostwall-protocol](frostwall-protocol/) | GRE tunnel security architecture for DDoS protection | BLOCKED |
| [mailcow-email-server-on-nc1](mailcow-email-server-on-nc1/) | Self-hosted @firefrostgaming.com email on NC1 | BLOCKED |
| [netdata-deployment](netdata-deployment/) | Real-time monitoring across all servers | READY |
| [self-hosted-ai-stack-on-tx1](self-hosted-ai-stack-on-tx1/) | AnythingLLM + Open WebUI deployment | BLOCKED |
| [command-center-security](command-center-security/) | Fail2Ban + SSH hardening for Command Center | READY |
| [luckperms-mysql-backend](luckperms-mysql-backend/) | Centralized permissions database | PLANNING |
| [staggered-server-restart-system](staggered-server-restart-system/) | Automated restart schedule for game servers | PLANNING |
| [world-backup-automation](world-backup-automation/) | Automated world backups to NextCloud | PLANNING |

---

## Development (6 tasks)

Tools, dashboards, and feature development.

| Task | Description | Status |
|------|-------------|--------|
| [whitelist-manager](whitelist-manager/) | Web dashboard for Minecraft whitelist management | READY |
| [blueprint-extension-installation-node-usage-status](blueprint-extension-installation-node-usage-status/) | Pterodactyl extension for node monitoring | PLANNING |
| [paymenter-theme-installation-citadel-theme](paymenter-theme-installation-citadel-theme/) | Custom theme for Paymenter billing | PLANNING |
| [nextcloud-upload-portal-for-meg](nextcloud-upload-portal-for-meg/) | Simple file upload interface for Meg | PLANNING |
| [scoped-gitea-token](scoped-gitea-token/) | Repository-scoped API token for Pokerole | READY |
| [game-server-startup-script-audit-&-optimization](game-server-startup-script-audit-&-optimization/) | Optimize server startup configurations | PLANNING |

---

## Content Creation (5 tasks)

Branding, media, and creative work.

| Task | Description | Status |
|------|-------------|--------|
| [terraria-branding-training-arc](terraria-branding-training-arc/) | 12-week training: learn game asset creation | PLANNING |
| ["coming-soon"-video-creation-(capcut)]("coming-soon"-video-creation-(capcut)/) | Marketing video for subscriber launch | PLANNING |
| [among-us-weekly-events-(phase-2-expansion)](among-us-weekly-events-(phase-2-expansion)/) | Community event series expansion | PLANNING |
| [discord-server-complete-reorganization](discord-server-complete-reorganization/) | Restructure Discord for subscriber model | PLANNING |
| [firefrost:-the-eternal-skyforge-(flagship-modpack)](firefrost:-the-eternal-skyforge-(flagship-modpack)/) | Custom Minecraft modpack development | PLANNING |

---

## Maintenance & Housekeeping (4 tasks)

Cleanup, optimization, and technical debt.

| Task | Description | Status |
|------|-------------|--------|
| [command-center-cleanup](command-center-cleanup/) | Organize Command Center root directory | READY |
| [mkdocs-decommission](mkdocs-decommission/) | Remove MkDocs (replaced by Wiki.js) | READY |
| [fix-frostwall-vs-firefrost-naming](fix-frostwall-vs-firefrost-naming/) | Standardize branding terminology | PLANNING |
| [consultant-photo-processing](consultant-photo-processing/) | Process and catalog consultant photos | COMPLETE |

---

## Documentation & Meta (4 tasks)

Documentation system improvements.

| Task | Description | Status |
|------|-------------|--------|
| [scope-document-corrections](scope-document-corrections/) | Fix scope doc inconsistencies | PLANNING |
| [workflow-guide-review-&-trim](workflow-guide-review-&-trim/) | Optimize workflow documentation | PLANNING |
| [department-structure-&-access-control-matrix](department-structure-&-access-control-matrix/) | Define departments for Wiki.js permissions | PLANNING |
| [vaultwarden-setup](vaultwarden-setup/) | Complete Vaultwarden SSH key + org setup | READY |

---

## Archived Tasks

**Location:** `docs/tasks/archive/2026/`

| Task | Completed | Archived |
|------|-----------|----------|
| nc1-cleanup | 2026-02-16 | 2026-03-18 |
| [Other completed tasks...] | [Date] | [Date] |

**Archive Policy:** Tasks move to archive 30 days after completion. See `docs/standards/task-documentation-standard.md` for details.

---

## Quick Stats

- **Total Tasks:** 27 active
- **Status Breakdown:**
  - READY: 8 tasks (~30%)
  - BLOCKED: 4 tasks (~15%)
  - PLANNING: 14 tasks (~52%)
  - IN-PROGRESS: 0 tasks
  - COMPLETE: 1 task (archived)

**Updated:** See Git commit history for this file

---

## Creating New Tasks

1. Run task creation script: `./automation/create-task.sh`
2. Fill in task README.md
3. Add entry to `docs/core/tasks.md`
4. Update this index with task category and one-liner

See `docs/standards/task-documentation-standard.md` for complete guide.

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️

Maintenance

Add to automation system (future enhancement):

# Script to auto-update task count in README.md
#!/bin/bash
# update-task-index-stats.sh

total=$(find docs/tasks/ -maxdepth 1 -type d | wc -l)
# ... count by status
# ... update README.md stats section

Success Criteria

• ✅ Index file created at docs/tasks/README.md
• ✅ All 27 tasks categorized and listed
• ✅ One-liner descriptions accurate
• ✅ Links to task directories work
• ✅ Quick stats section shows current counts
• ✅ Archive section prepared for future use

---

6. Define Simple Task Threshold

Problem: Creating full directory structure for 15-minute housekeeping tasks creates unnecessary overhead

Solution: Add clear guidelines to standard for when to use inline vs. directory approach

Time: 30 minutes

Implementation

File: docs/standards/task-documentation-standard.md

Add new section after "📁 DIRECTORY STRUCTURE":

## WHEN TO USE INLINE VS DIRECTORY

Not every task needs a directory. Use this decision tree:

### Decision Matrix

| Question | Answer | Action |
|----------|--------|--------|
| Task takes <15 minutes | Yes | **Inline in tasks.md** (no directory) |
| Task is one-time housekeeping | Yes | **Inline** (unless >15 min) |
| Task needs supporting docs | Yes | **Directory required** |
| Task will be referenced later | Yes | **Directory recommended** |
| Task has multiple phases | Yes | **Directory required** |
| Task requires troubleshooting guide | Yes | **Directory required** |
| Complex prerequisites | Yes | **Directory required** |
| Creates reusable tool/service | Yes | **Directory required** |

### Inline Task Format

For tasks that don't need directories:

```markdown
### [#]. [Task Name]
**Time:** [estimate]  
**Status:** [status]

**What:** [One sentence description]

**How:**
```bash
# Commands or brief steps
command1
command2

Success:

• [Criterion 1]
• [Criterion 2]

Done: [checkmark when complete]

### Directory Task Format

Use standard directory structure (see main sections above).

---

### Examples

#### Example 1: Inline Task (Delete Old Backups)

```markdown
### 15. Delete Old Gitea Backups
**Time:** 5 minutes  
**Status:** READY

**What:** Remove Gitea backup files older than 90 days from Command Center.

**How:**
```bash
ssh root@command-center
find /root/backups/gitea/ -name "*.tar.gz" -mtime +90 -delete
find /root/backups/gitea/ -name "*.sql" -mtime +90 -delete

Success:

• Only backups from last 90 days remain
• Disk space freed

Done: [ ]

#### Example 2: Directory Task (Even Though Simple)

**When:** 15-minute task that needs to be referenced later

```markdown
### 16. Update DNS Records for New Service
**Time:** 15 minutes  
**Status:** READY  
**Documentation:** `docs/tasks/dns-update-new-service/`

**What:** Add DNS records for whitelist.firefrostgaming.com

**Why directory?** DNS changes are referenced frequently when troubleshooting. Having dedicated doc makes it easy to find "what DNS records exist and when were they added?"

See task directory for complete DNS record list and verification steps.

---

Gray Areas (Use Judgment)

Borderline cases:

• 10-15 minute tasks that might grow
• Simple tasks that create precedent for future similar tasks
• One-time tasks that team will ask about later

Recommendation: When in doubt, create directory. Easier to have empty directory than to reconstruct context later.

---

Migration of Existing Inline Tasks

Tasks currently inline in tasks.md can:

1. Stay inline if they meet criteria above
2. Get promoted to directory if they grow in scope
3. Get archived to separate "completed inline tasks" section

No forced migration: Existing inline tasks don't need to be moved unless they evolve.

#### Success Criteria

- ✅ Decision matrix added to standard
- ✅ Inline task format template provided
- ✅ Examples show both approaches
- ✅ Gray area guidance included
- ✅ Migration policy for existing tasks defined

---

### 7. Enforce Filename Conventions

**Problem:** At least one task directory uses special characters in name (`"coming-soon"-video-creation-(capcut)`)

**Solution:** Add validation and fix existing violations

**Time:** 30 minutes

#### Implementation

**Step 1: Create Validation Script**

**File:** `automation/validate-task-names.sh`

```bash
#!/bin/bash
# validate-task-names.sh
# Validates all task directory names follow naming convention

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'

errors=0

echo "Validating task directory names..."
echo ""

for dir in docs/tasks/*/; do
  # Skip if not a directory
  [ -d "$dir" ] || continue
  
  name=$(basename "$dir")
  
  # Check if name matches pattern: lowercase letters, numbers, hyphens only
  if [[ ! $name =~ ^[a-z0-9-]+$ ]]; then
    echo -e "${RED}✗ INVALID:${NC} $name"
    echo "  Must be lowercase letters, numbers, and hyphens only"
    echo "  Found invalid characters"
    errors=$((errors + 1))
  else
    echo -e "${GREEN}✓${NC} $name"
  fi
done

echo ""

if [ $errors -gt 0 ]; then
  echo -e "${RED}Found $errors invalid task directory name(s)${NC}"
  echo ""
  echo "To fix:"
  echo "1. Rename directory to valid format"
  echo "2. Update all references (tasks.md, DOCUMENT-INDEX.md, other docs)"
  echo "3. Commit with message: 'Rename task directory to follow naming standard'"
  exit 1
else
  echo -e "${GREEN}All task directory names are valid${NC}"
  exit 0
fi

chmod +x automation/validate-task-names.sh

Step 2: Run Validation

./automation/validate-task-names.sh

# Expected output:
# ✗ INVALID: "coming-soon"-video-creation-(capcut)
#   Must be lowercase letters, numbers, and hyphens only

Step 3: Fix Violations

# Rename directory
mv 'docs/tasks/"coming-soon"-video-creation-(capcut)' \
   'docs/tasks/coming-soon-video-creation-capcut'

# Update references in tasks.md
sed -i 's|docs/tasks/"coming-soon"-video-creation-(capcut)|docs/tasks/coming-soon-video-creation-capcut|g' docs/core/tasks.md

# Update references in DOCUMENT-INDEX.md if present
sed -i 's|"coming-soon"-video-creation-(capcut)|coming-soon-video-creation-capcut|g' DOCUMENT-INDEX.md

# Update any internal links in other docs
grep -r '"coming-soon"-video-creation-(capcut)' docs/ --files-with-matches | while read file; do
  sed -i 's|"coming-soon"-video-creation-(capcut)|coming-soon-video-creation-capcut|g' "$file"
done

# Commit
git add -A
git commit -m "Rename task directory to follow naming standard

- Renamed: \"coming-soon\"-video-creation-(capcut) → coming-soon-video-creation-capcut
- Updated all references in tasks.md, DOCUMENT-INDEX.md
- Enforces FFG-STD-002 naming convention: lowercase, numbers, hyphens only"

Step 4: Add to CI/Pre-commit

File: .githooks/pre-commit (or add to existing)

#!/bin/bash
# Pre-commit hook: Validate task directory names

./automation/validate-task-names.sh
if [ $? -ne 0 ]; then
  echo ""
  echo "Commit rejected: Task directory naming convention violated"
  echo "Fix the naming issue and try again"
  exit 1
fi

Enable hooks:

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

Step 5: Update Standard

Add to task-documentation-standard.md → "Naming Conventions" section:

### Validation

**Automated validation:**
```bash
# Check all task names
./automation/validate-task-names.sh

Valid examples:

• ✅ whitelist-manager
• ✅ self-hosted-ai-stack-on-tx1
• ✅ terraria-branding-training-arc
• ✅ coming-soon-video-creation-capcut

Invalid examples:

• ❌ "coming-soon"-video (quotes not allowed)
• ❌ Task_Name (underscores not allowed)
• ❌ MyTask (uppercase not allowed)
• ❌ new task (spaces not allowed)
• ❌ task-name! (special chars not allowed)

Enforcement:

• Pre-commit hook prevents invalid names
• CI/CD pipeline checks on pull requests
• Manual validation: ./automation/validate-task-names.sh

#### Success Criteria

- ✅ Validation script created and tested
- ✅ All existing violations fixed
- ✅ Pre-commit hook installed
- ✅ Standard document updated with validation section
- ✅ Future invalid names blocked automatically

---

## MEDIUM-TERM PRIORITY (Weeks 3-4)

### 8. Consider Tiered Subdirectories

**Problem:** 27 flat directories will become unwieldy at 50-100+ tasks

**Solution:** Implement category-based organization (but keep physical paths predictable)

**Time:** 2-3 hours

#### Analysis

**Pros of tiered structure:**
- Related tasks grouped together
- Easier to find tasks in same domain
- Scales better to 100+ tasks
- Categories match mental model

**Cons of tiered structure:**
- Adds one level of nesting
- Category boundaries can be fuzzy
- Migration effort for existing tasks
- Longer paths to type

#### Recommended Approach: **Hybrid System**

Keep physical directories flat for simplicity, but organize logically in documentation.

**Physical structure (actual directories):**

docs/tasks/ ├── whitelist-manager/ ├── frostwall-protocol/ ├── mailcow-email/ └── ... (all tasks alphabetically)

**Logical structure (in README.md index):**
```markdown
## Infrastructure
- [frostwall-protocol](frostwall-protocol/)
- [mailcow-email](mailcow-email/)

## Development
- [whitelist-manager](whitelist-manager/)

Benefits:

• ✅ Easy to find tasks (categorized in index)
• ✅ Easy to reference (simple paths)
• ✅ No migration needed
• ✅ Works with tab completion
• ✅ Scales indefinitely (index can reorganize without moving files)

Implementation

Already done in Recommendation #5 (Create Task Directory Index)

The docs/tasks/README.md file provides category-based organization without changing physical structure.

Alternative (if truly needed at scale):

If task count exceeds 100 and flat structure becomes problematic, implement actual subdirectories:

# Migration script (future use if needed)
# DO NOT RUN NOW - only if >100 tasks

mkdir -p docs/tasks/{infrastructure,development,content,maintenance,documentation}

# Move tasks to categories
mv docs/tasks/frostwall-protocol docs/tasks/infrastructure/
mv docs/tasks/whitelist-manager docs/tasks/development/
# ... etc

# Update all references
find docs/ -name "*.md" -exec sed -i 's|docs/tasks/frostwall-protocol|docs/tasks/infrastructure/frostwall-protocol|g' {} \;

Decision point: Revisit when task count reaches 75-100

Success Criteria

• ✅ Index-based organization implemented (already done in #5)
• ✅ Physical structure remains flat (no change needed now)
• ✅ Migration plan documented for future (if needed)
• ✅ Decision point established (75-100 tasks)

---

9. Define Archive Policy

Problem: No clear process for archiving completed tasks; they accumulate in active directory

Solution: Establish 30-day grace period, then move to archive with redirect

Time: 1 hour

Implementation

Step 1: Add Archive Policy to Standard

File: docs/standards/task-documentation-standard.md

Add new section after "Document Lifecycle":

## ARCHIVE POLICY

### When Tasks Are Archived

**Completed tasks:**
1. Marked COMPLETE in tasks.md with completion date
2. Stay in active directory for **30 days** (grace period for reference)
3. After 30 days, moved to `docs/tasks/archive/[year]/[task-name]/`
4. Active directory replaced with redirect README

**Grace period rationale:**
- Allows recent reference without searching archive
- Troubleshooting may reference recently completed work
- Easy rollback if task needs reopening

### Archive Directory Structure

docs/tasks/ ├── archive/ │ ├── 2026/ │ │ ├── nc1-cleanup/ │ │ │ ├── README.md │ │ │ └── [original docs] │ │ └── consultant-photo-processing/ │ └── 2027/ │ └── [future archived tasks] └── [active tasks]/

### Archive Procedure

**Step 1: Identify tasks ready for archive**

```bash
# Find tasks completed >30 days ago
grep -r "Completed:" docs/tasks/*/README.md | while read line; do
  # Parse completion date, check if >30 days old
  # (Implementation left as automation task)
done

Step 2: Move task to archive

# Variables
TASK_NAME="nc1-cleanup"
YEAR="2026"
COMPLETION_DATE="2026-02-16"

# Create archive directory
mkdir -p "docs/tasks/archive/$YEAR"

# Move task directory
mv "docs/tasks/$TASK_NAME" "docs/tasks/archive/$YEAR/"

# Create redirect in original location
cat > "docs/tasks/$TASK_NAME/README.md" <<EOF
# $TASK_NAME - ARCHIVED

**Status:** ARCHIVED  
**Completed:** $COMPLETION_DATE  
**Archived:** $(date +%Y-%m-%d)

---

## This task has been archived

**Archived location:** \`docs/tasks/archive/$YEAR/$TASK_NAME/\`

This task was completed on $COMPLETION_DATE and archived after the 30-day grace period.

**To view archived documentation:**
\`\`\`bash
cd docs/tasks/archive/$YEAR/$TASK_NAME/
\`\`\`

**For current tasks:** See \`docs/core/tasks.md\`

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
EOF

Step 3: Update references

# Update tasks.md
# Move from active section to archived section

# Update docs/tasks/README.md
# Move from category to "Archived Tasks" section

Step 4: Commit

git add docs/tasks/$TASK_NAME docs/tasks/archive/$YEAR/$TASK_NAME
git commit -m "Archive $TASK_NAME (completed $COMPLETION_DATE)

- Moved to docs/tasks/archive/$YEAR/$TASK_NAME/
- Created redirect README in original location
- Updated tasks.md and task index"

Redirect README Template

File: docs/tasks/[archived-task-name]/README.md

# [Task Name] - ARCHIVED

**Status:** ARCHIVED  
**Completed:** [Date]  
**Archived:** [Date]

---

## This task has been archived

**Archived location:** `docs/tasks/archive/[year]/[task-name]/`

This task was completed on [completion date] and archived after the 30-day grace period.

**To view archived documentation:**
```bash
cd docs/tasks/archive/[year]/[task-name]/

For current tasks: See docs/core/tasks.md

---

Fire + Frost + Foundation = Where Love Builds Legacy 💙🔥❄️

### Automation

**Future enhancement:** Automated archive reminder

```bash
# automation/check-archive-candidates.sh
#!/bin/bash
# Finds tasks completed >30 days ago

echo "Tasks ready for archive:"
# (Implementation as needed)

Run monthly to identify archive candidates.

Archive Maintenance

Quarterly review:

• Check archive for tasks that can be deleted (>2 years old, no reference value)
• Compress large archived task directories
• Update archive index

Archive index: docs/tasks/archive/README.md

# Archived Tasks Index

| Task | Completed | Archived | Year |
|------|-----------|----------|------|
| nc1-cleanup | 2026-02-16 | 2026-03-18 | [2026](2026/) |
| consultant-photo-processing | 2026-02-16 | 2026-03-18 | [2026](2026/) |

#### Success Criteria

- ✅ Archive policy documented in standard
- ✅ Archive directory structure created
- ✅ Archive procedure detailed with commands
- ✅ Redirect README template provided
- ✅ Archive index created
- ✅ Automation enhancement identified (optional)

---

### 10. Add Automated Link Checking

**Problem:** As documentation grows, broken internal links accumulate

**Solution:** Automated validation of markdown links

**Time:** 45 minutes

#### Implementation

**Step 1: Install markdown-link-check**

```bash
# On Command Center or CI system
npm install -g markdown-link-check

Step 2: Create Link Check Script

File: automation/check-links.sh

#!/bin/bash
# check-links.sh - Validate all markdown links

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

echo -e "${GREEN}=== Markdown Link Checker ===${NC}\n"

# Config file for markdown-link-check
cat > /tmp/mlc-config.json <<EOF
{
  "ignorePatterns": [
    {
      "pattern": "^https://git.firefrostgaming.com"
    },
    {
      "pattern": "^mailto:"
    }
  ],
  "timeout": "20s",
  "retryOn429": true,
  "retryCount": 3,
  "fallbackRetryDelay": "30s"
}
EOF

# Find all markdown files
files=$(find docs/ -name "*.md" -not -path "*/archive/*")

total=0
errors=0

for file in $files; do
  total=$((total + 1))
  
  echo -e "${YELLOW}Checking:${NC} $file"
  
  if markdown-link-check "$file" -c /tmp/mlc-config.json -q; then
    echo -e "${GREEN}✓ OK${NC}"
  else
    echo -e "${RED}✗ BROKEN LINKS FOUND${NC}"
    errors=$((errors + 1))
  fi
  
  echo ""
done

# Summary
echo -e "${GREEN}=== Summary ===${NC}"
echo "Files checked: $total"
echo "Files with errors: $errors"

if [ $errors -gt 0 ]; then
  echo -e "\n${RED}Found broken links in $errors file(s)${NC}"
  echo "Review output above for details"
  exit 1
else
  echo -e "\n${GREEN}All links valid!${NC}"
  exit 0
fi

chmod +x automation/check-links.sh

Step 3: Add to Automation System

# Create weekly link check task
cat > automation/queue/link-check-weekly.sh <<EOF
#!/bin/bash
# Weekly link validation

cd /path/to/firefrost-operations-manual
./automation/check-links.sh > automation/logs/link-check-$(date +%Y%m%d).log 2>&1

# If errors found, create notification
if [ \$? -ne 0 ]; then
  echo "Broken links detected in operations manual" > /tmp/link-check-alert.txt
  echo "See automation/logs/link-check-$(date +%Y%m%d).log" >> /tmp/link-check-alert.txt
  # Send notification (Discord webhook, email, etc.)
fi
EOF

chmod +x automation/queue/link-check-weekly.sh

# Schedule with cron
# crontab -e
# 0 9 * * 1 /path/to/automation/queue/link-check-weekly.sh

Step 4: Document in Automation Usage

Add to automation/USAGE.md:

## Link Validation

**Manual check:**
```bash
./automation/check-links.sh

Automated schedule: Runs every Monday at 9 AM

Output: automation/logs/link-check-YYYYMMDD.log

Errors: Alert sent if broken links found

Fix broken links:

1. Review log file for broken URLs
2. Update markdown files to fix links
3. Re-run validation to confirm
4. Commit fixes

**Step 5: Add Quality Check to Standard**

Update `task-documentation-standard.md` → Quality Standards section:

```markdown
### Link Validation

All internal links must be valid and maintained.

**Before committing:**
```bash
# Check links in changed files
markdown-link-check docs/path/to/file.md

Automated checking:

• Weekly validation runs Monday mornings
• Alerts sent if broken links detected
• See automation/logs/ for results

Common link errors:

• Typos in file paths
• Files renamed without updating links
• Moved directories
• Deleted referenced documents

Prevention:

• Use relative paths for internal links
• Test links before committing
• Update all references when moving/renaming files

#### Success Criteria

- ✅ markdown-link-check installed
- ✅ Link check script created and tested
- ✅ Weekly automation scheduled
- ✅ Logging configured
- ✅ Documentation updated
- ✅ Alert system configured (optional)

---

## IMPLEMENTATION SUMMARY

### Time Investment

| Priority | Tasks | Total Time |
|----------|-------|------------|
| Immediate (Week 1) | 4 tasks | 4-6 hours |
| Short-term (Weeks 2-3) | 3 tasks | 4-5 hours |
| Medium-term (Weeks 3-4) | 3 tasks | 4-5 hours |
| **Total** | **10 tasks** | **12-16 hours** |

### Rollout Schedule

**Week 1:**
- Day 1: Standardize status terminology (1-2 hrs)
- Day 2: Create task creation script (30 min)
- Day 3: Migrate external docs (2-3 hrs)
- Day 4: Update DOCUMENT-INDEX.md (20 min)

**Week 2:**
- Day 1: Create task directory index (1 hr)
- Day 2: Define simple task threshold (30 min)
- Day 3: Enforce filename conventions (30 min)

**Week 3:**
- Day 1: Review tiered subdirectories (decided: not needed yet)
- Day 2: Define archive policy (1 hr)
- Day 3: Add automated link checking (45 min)

**Week 4:**
- Buffer for testing, documentation, and refinement

### Success Metrics

After all improvements:
- ✅ Zero status terminology inconsistencies
- ✅ New tasks created in <5 minutes with script
- ✅ Zero ambiguous "current" vs "migration target" docs
- ✅ DOCUMENT-INDEX accurately reflects task system
- ✅ Task directory index enables browsing without status clutter
- ✅ Clear guidance for simple vs complex tasks
- ✅ Zero invalid task directory names
- ✅ Archive policy ready for first completed task
- ✅ Automated link checking prevents broken references

### Dependencies

Immediate:

1. Status terminology → (none)
2. Task creation script → (none)
3. External doc migration → (none)
4. Update DOCUMENT-INDEX → (none)

Short-term: 5. Task directory index → #1 (status terminology) 6. Simple task threshold → (none) 7. Filename conventions → (none)

Medium-term: 8. Tiered subdirectories → #5 (task index) 9. Archive policy → #1 (status terminology) 10. Link checking → (none)

All tasks can be executed in parallel except #5 depends on #1.

---

## REMAINING RECOMMENDATIONS

### Lower Priority (Months 2-3)

These are valuable but can wait until high-priority items are complete:

**11. Create Quick-Start Guide (R6.1)**
- Simplified version of standard for rapid onboarding
- Time: 1 hour
- Benefit: Reduces new user friction

**12. Add Glossary to Standard (R6.3)**
- Project-specific and technical term definitions
- Time: 2 hours
- Benefit: Improves accessibility for new staff/future readers

**13. Add Complex Task Example (R3.4)**
- Fully documented multi-subdirectory task
- Time: 3-4 hours (during task execution)
- Benefit: Demonstrates pattern for large tasks

**14. Implement Quality Review Process (R5.4)**
- Defined review cadence and checklists
- Time: 1 hour
- Benefit: Maintains quality at scale

**15. Create Maintenance Dashboard (R5.3)**
- Automated documentation health report
- Time: 2-3 hours
- Benefit: Visibility into doc completeness

### Optional Enhancements

Nice to have but not critical:

- Task tagging system for grep-based search
- YAML frontmatter for structured metadata
- Markdown linter configuration
- Dependency visualization (Mermaid graphs)
- Search integration (MkDocs/Wiki.js)
- Git LFS policy for large files
- Automated README timestamp updates

---

## CONCLUSION

This implementation guide covers the **top 10 priority improvements** identified in the documentation review. Total time investment of 12-16 hours over 4 weeks will:

1. **Eliminate confusion** (status terminology, external docs)
2. **Reduce friction** (task creation script, simple task threshold)
3. **Improve discovery** (task index, DOCUMENT-INDEX updates)
4. **Enforce quality** (filename validation, link checking)
5. **Prepare for scale** (archive policy, organizational planning)

Each improvement includes clear rationale, step-by-step procedures, success criteria, and time estimates. Implementation can be done incrementally without disrupting ongoing work.

**Recommended approach:** Execute in order presented, validate each improvement before moving to next, and commit changes frequently with clear commit messages.

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️