676 lines
14 KiB
Markdown
676 lines
14 KiB
Markdown
---
|
|
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
|