---
description: "Planning Document Standards: Format and structure requirements for migration plans, implementation guides, and project roadmaps."
applyTo: "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:

```markdown
# [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:**
```markdown
# 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:**

```markdown
## 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:**

```markdown
## 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:**

```markdown
## 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:**

```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**

```markdown
---

**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:**
```markdown
```bash
# Good: Language specified
```

```markdown
```
# Bad: Generic code block
```
```

**Include expected outputs:**
```bash
ansible --version
# Expected: ansible [core 2.x.x] or newer
```

**Add comments explaining why:**
```bash
# 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:**
```markdown
**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:**
```markdown
- [ ] Ansible toolchain installed
- [ ] SSH keys distributed
- [ ] First playbook run successful
```

**Markdown tables for comparisons:**
```markdown
| Option | Pros | Cons | Time |
|--------|------|------|------|
| A | Fast | Complex | 1h |
| B | Simple | Slow | 3h |
```

### Links & References

**Internal links use relative paths:**
```markdown
See [ansible/.ansible-lint](ansible/.ansible-lint) for configuration.
```

**External links use full URLs:**
```markdown
Git-crypt Documentation: https://github.com/AGWA/git-crypt
```

**Related documentation section:**
```markdown
## 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:

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

```markdown
## Security Considerations

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

### Maintenance & Next Steps

For ongoing operations:

```markdown
## Maintenance & Next Steps

### Ongoing Operations

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

### Future Enhancements

1. **[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:**
```markdown
## Phase 1: Setup
### Step 1: Install tools
```

✅ **Correct format:**
```markdown
## Phase 1: Setup
**Estimated Time:** 20-30 minutes

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

---

❌ **Vague success criteria:**
```markdown
- Everything works
- No errors
```

✅ **Specific validation:**
```markdown
- ✅ 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:**
```bash
git-crypt unlock
cat nodes/waldorf/plex/.env.secrets
```

✅ **Commands with verification:**
```bash
# 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):**
```markdown
# Setup Guide
## Step 1
## Step 2
## Step 3
[... 20 more steps ...]
```

✅ **Hierarchical organization:**
```markdown
# 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:

```markdown
# [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:**
```bash
# 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