nathan/homelab
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Releases Wiki Activity

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

Browse Source
This commit is contained in:
nathan 2026-04-12 01:31:43 -04:00
parent 2531cb4705
commit 325c4b98a5
1 changed files with 675 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

675
.github/instructions/style.plans.instructions.md vendored Normal file
View File

@ -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