nathan 325c4b98a5 feat(documentation): add planning document standards for migration plans and implementation guides

2026-04-12 01:31:43 -04:00

14 KiB

Raw Blame History

description, applyTo

description	applyTo
Planning Document Standards: Format and structure requirements for migration plans, implementation guides, and project roadmaps.	documentation/plans/*/.md

Planning Document Standards

Purpose

This document defines the structure, formatting, and content requirements for all planning documents stored in documentation/plans/. These standards ensure consistency, enable accurate time estimation, and provide clear execution pathways for infrastructure changes.

Document Types

Migration Plans

Files prefixed with plan- that detail transitioning from one state to another.

Examples:

plan-gitcryptMigration.md — Implementing git-crypt for secret management
plan-ansibleSetup.md — Setting up Ansible control node
plan-promptDistribution.md — Centralizing prompt repository

Implementation Guides

Step-by-step instructions for deploying new technologies or systems.

Roadmaps

Long-term strategic plans spanning multiple phases or quarters.

Required Document Structure

1. Header Section

Every plan must begin with:

# [Descriptive Title]: [Specific Goal]

## Overview

[2-3 sentence summary of what this plan accomplishes and why it matters]

**[Primary Metric]:** [Value/Target]
**[Secondary Metric]:** [Value/Target] (optional)
**End State:** [Concrete description of success]

**Estimated Time to Complete:** X-Y hours (first-time setup) | A-B hours (experienced operator)

Example:

# Ansible Control Node Setup: Path to Production Readiness

## Overview

Transform **Watchtower** (Raspberry Pi 5) into a production-ready Ansible control node capable of managing the entire homelab infrastructure.

**Control Node:** Watchtower (10.0.0.200) — Raspberry Pi 5, ARM Cortex-A76, 16GB RAM
**Managed Nodes:** Heimdall (10.0.0.151), Waldorf (10.0.0.251), Watchtower (localhost)
**End State:** Fully configured Ansible environment with validated connectivity, encrypted secrets, and role scaffolding.

**Estimated Time to Complete:** 2-3 hours (first-time setup) | 45-60 minutes (experienced operator)

2. Time Breakdown Table

Required immediately after Overview section:

## Time Breakdown by Phase

| Phase | Description | Time Estimate |
|-------|-------------|---------------|
| **Phase 1** | [Phase Name] | XX-YY minutes |
| **Phase 2** | [Phase Name] | XX-YY minutes |
| **Phase 3** | [Phase Name] | XX-YY minutes |
| **Phase N** | [Phase Name] | XX-YY minutes |
| **Total** | End-to-End [Process Name] | **X-Y hours** |

Guidelines:

Use bold for phase numbers and total row
Time estimates should be ranges (min-max) in minutes or hours
Total should sum to the overall estimate in the Overview
Include 3-6 phases typically (not too granular, not too broad)

For plans with multiple options:

## Time Breakdown by Implementation Option

| Option | Approach | Initial Setup Time | Ongoing Maintenance |
|--------|----------|-------------------|---------------------|
| **Option 1** | [Method] | X-Y hours | Z min/operation |
| **Option 2** | [Method] | X-Y hours | Z min/operation |
| **Option 3** | [Method] | X-Y hours | Z min/operation |

**Recommended:** Option [N] (detailed time breakdown below)

### Option [N]: Detailed Phase Breakdown

| Phase | Description | Time Estimate |
|-------|-------------|---------------|
[Standard phase table as above]

3. Prerequisites Section

Required before Phase 1:

## Prerequisites

- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]
- [ ] [Optional: Requirement 4 (optional, but recommended)]

Guidelines:

Use checkboxes (- [ ]) for trackability
List in order of validation (check access before checking software versions)
Distinguish between required and optional prerequisites
Include both technical and knowledge prerequisites

4. Phase Sections

Each phase must include:

## Phase [N]: [Phase Name]
**Estimated Time:** XX-YY minutes

[1-2 sentence phase description explaining the goal]

### Step [N]: [Step Name]
**Time:** X-Y minutes

[Step instructions with code blocks, explanations, and verification steps]

**[Optional Section: Why/Security Note/Troubleshooting]:**
[Additional context if needed]

Step-Level Requirements:

Each step must have individual time estimate
Include verification commands where applicable
Add # Expected: [output] comments to commands
Use consistent heading levels (## for Phase, ### for Step)

Example:

## Phase 1: Control Node Foundation (Watchtower Setup)
**Estimated Time:** 20-30 minutes

### Step 1: Install Ansible Toolchain
**Time:** 10-15 minutes (depends on network speed)

Connect to Watchtower via SSH and install the complete Ansible stack:

```bash
# SSH to Watchtower
ssh chester@10.0.0.200

# Update package index
sudo apt update

# Verify Ansible installation
ansible --version
# Expected: ansible [core 2.x.x] or newer

Why these tools:

ansible: Execution engine
ansible-lint: Code quality enforcement


---

### 5. Troubleshooting Section

**Required before final checklist:**

```markdown
## Troubleshooting

### Issue: [Symptom Description]

**Cause:** [Root cause explanation]

**Fix:**
```bash
[Commands to resolve]

[Optional: Additional context or prevention tips]


**Guidelines:**
- Anticipate 3-5 common failure modes
- Use consistent format: Issue → Cause → Fix
- Include verification steps in the fix
- Order by likelihood (most common first)

---

### 6. Summary/Checklist Section

**Required at end of document:**

```markdown
## Summary Checklist

- [ ] [Major milestone 1]
- [ ] [Major milestone 2]
- [ ] [Major milestone 3]
- [ ] [Verification step]
- [ ] [Documentation updated]
- [ ] [Changes committed to Git]

**Environment Status:** 🟢 **PRODUCTION READY** | 🟡 **TESTING** | 🔴 **NOT READY**

Optional sections:

## Migration Checklist

**Pre-Migration:**
- [ ] [Backup step]
- [ ] [Verification step]

**Migration Steps:**
- [ ] [Core steps from the plan]

**Post-Migration:**
- [ ] [Validation]
- [ ] [Documentation]
- [ ] [Cleanup]

7. Document Metadata (Footer)

Required at very end:

---

**Document Version:** X.Y
**Last Updated:** [Month DD, YYYY]
**Author:** [Author Name/Tool]
**Review Cycle:** [Quarterly | Monthly | After infrastructure changes]

Formatting Standards

Time Estimates

Range Format:

Use ranges for uncertainty: 10-15 minutes, 2-3 hours
Larger range for first-time: 2-3 hours (first-time)
Smaller range for experienced: 45-60 minutes (experienced)

Never use:

Exact times without ranges: ❌ 15 minutes
Vague estimates: ❌ about an hour, quickly

Code Blocks

Always specify language:

```bash
# Good: Language specified

Bad: Generic code block

Include expected outputs:

ansible --version
# Expected: ansible [core 2.x.x] or newer

Add comments explaining why:

# Generate ED25519 key (modern, secure, fast)
ssh-keygen -t ed25519 -C "ansible@watchtower"

Emphasis & Highlighting

Use bold for:

Phase names in tables
Important: warnings or critical notes
Goal: objective statements
Key metrics in overview

Use inline code for:

File paths: ansible/ansible.cfg
Commands: git-crypt unlock
Variables: vault_password_file
Package names: ansible-lint

Use INFO blocks for decisions:

**Key Decisions:**
- `host_key_checking = False`: Simplifies homelab automation (acceptable for trusted private network)
- `forks = 3`: Limits parallel execution (prevents overwhelming Pi resources)

Lists & Tables

Checkbox lists for trackable items:

- [ ] Ansible toolchain installed
- [ ] SSH keys distributed
- [ ] First playbook run successful

Markdown tables for comparisons:

| Option | Pros | Cons | Time |
|--------|------|------|------|
| A | Fast | Complex | 1h |
| B | Simple | Slow | 3h |

Links & References

Internal links use relative paths:

See [ansible/.ansible-lint](ansible/.ansible-lint) for configuration.

External links use full URLs:

Git-crypt Documentation: https://github.com/AGWA/git-crypt

Related documentation section:

## Related Documentation

- [SECURITY_AUDIT_REPORT.md](../documentation/SECURITY_AUDIT_REPORT.md) - Security findings
- [SOP-001](../documentation/SOPs/SOP-001-Example.md) - Related procedure

Optional Sections (Use When Applicable)

Rollback Plan

For destructive or risky migrations:

## Rollback Plan

If [technology] causes issues:

```bash
# 1. Stop service
# 2. Restore backup
# 3. Revert configuration

Recovery Time: Estimated X-Y minutes


### Migration Strategy (Multi-Week Plans)

For staged rollouts:

```markdown
## Migration Strategy
**Total Timeline:** [N] weeks (staged rollout) | [M] days (aggressive deployment)

### Week 1: [Phase Name]
**Time:** X-Y hours

[Objectives]

### Week 2: [Phase Name]
**Time:** X-Y hours

[Objectives]

Security Considerations

For security-sensitive plans:

## Security Considerations

### [Area of Concern]
- [Risk description]
- [Mitigation strategy]
- [Verification method]

Maintenance & Next Steps

For ongoing operations:

## Maintenance & Next Steps

### Ongoing Operations

**[Operation Name]:**
```bash
[Command]

Future Enhancements

[Enhancement Name]:
- [Description]
- [Estimated effort]


---

## Success Criteria Template

Each plan should define measurable success criteria:

```markdown
## Success Criteria

- ✅ [Technical validation 1]
- ✅ [Technical validation 2]
- ✅ [Functional test passed]
- ✅ [Documentation updated]
- ✅ [Zero errors in logs]

**Estimated Migration Time:** [Same as in overview]
**Maintenance:** [Ongoing time commitment]

File Naming Convention

Pattern: plan-[technology][Action].md

Examples:

plan-ansibleSetup.md — Setup/installation guide
plan-gitcryptMigration.md — Migration from one state to another
plan-promptDistribution.md — Distribution/deployment plan

Rules:

Use camelCase for multi-word components
No spaces or special characters
Prefix always plan-
Suffix always .md

Quality Checklist

Before committing a planning document, verify:

Overview includes total time estimate
Time breakdown table present and accurate
Prerequisites listed with checkboxes
Each phase has time estimate
Each step has individual time estimate
Code blocks specify language
Expected outputs documented
Troubleshooting section included
Summary checklist present
Document metadata complete
All links are valid
Formatting consistent with examples
Success criteria defined
Related documentation referenced

Anti-Patterns (Common Mistakes)

❌ Missing time estimates:

## Phase 1: Setup
### Step 1: Install tools

✅ Correct format:

## Phase 1: Setup
**Estimated Time:** 20-30 minutes

### Step 1: Install tools
**Time:** 10-15 minutes

❌ Vague success criteria:

- Everything works
- No errors

✅ Specific validation:

- ✅ All nodes respond to `ansible all -m ping`
- ✅ Zero lint errors when running `ansible-lint playbooks/*.yml`
- ✅ Validation playbook completes with exit code 0

❌ Commands without context:

git-crypt unlock
cat nodes/waldorf/plex/.env.secrets

✅ Commands with verification:

# Unlock with the key
git-crypt unlock ~/homelab-secrets.key

# Verify decryption worked
cat nodes/waldorf/plex/.env.secrets
# Expected: plaintext secrets (not binary data)

❌ Flat structure (no phases):

# Setup Guide
## Step 1
## Step 2
## Step 3
[... 20 more steps ...]

✅ Hierarchical organization:

# Setup Guide

## Phase 1: Foundation (30-40 min)
### Step 1 (10 min)
### Step 2 (20 min)

## Phase 2: Configuration (20-30 min)
### Step 3 (15 min)
### Step 4 (10 min)

Example Template

Use this as a starting point for new planning documents:

# [Title]: [Goal]

## Overview

[Description]

**[Key Metric 1]:** [Value]
**[Key Metric 2]:** [Value]
**End State:** [Success description]

**Estimated Time to Complete:** X-Y hours (first-time) | A-B hours (experienced)

---

## Time Breakdown by Phase

| Phase | Description | Time Estimate |
|-------|-------------|---------------|
| **Phase 1** | [Name] | XX-YY minutes |
| **Phase 2** | [Name] | XX-YY minutes |
| **Total** | End-to-End | **X-Y hours** |

---

## Prerequisites

- [ ] [Requirement 1]
- [ ] [Requirement 2]

---

## Phase 1: [Name]
**Estimated Time:** XX-YY minutes

### Step 1: [Action]
**Time:** X-Y minutes

```bash
# Commands

Phase 2: [Name]

Estimated Time: XX-YY minutes

Step 2: [Action]

Time: X-Y minutes

Troubleshooting

Issue: [Problem]

Cause: [Explanation] Fix:

# Solution

Summary Checklist

[Milestone 1]
[Milestone 2]

Environment Status: 🟢 PRODUCTION READY

Document Version: 1.0 Last Updated: [Date] Author: [Name] Review Cycle: Quarterly


---

## Enforcement

This standard applies to:
- All files in `documentation/plans/`
- Migration guides
- Implementation roadmaps
- Multi-phase technical projects

**Exclusions:**
- Quick reference guides (use KBA format instead)
- Single-step procedures (use SOP format instead)
- Architecture diagrams (standalone)

---

**Document Version:** 1.0
**Last Updated:** April 12, 2026
**Author:** FrankGPT (Ansible Architect Mode)
**Review Cycle:** Quarterly or when planning format needs evolve

14 KiB Raw Blame History