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

2026-04-12 01:31:43 -04:00 · 2026-04-12 01:31:43 -04:00 · 325c4b98a5
commit 325c4b98a5
parent 2531cb4705
1 changed files with 675 additions and 0 deletions
--- a/.github/instructions/style.plans.instructions.md
+++ b/.github/instructions/style.plans.instructions.md
@ -0,0 +1,675 @@
+---
+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