nixos-servers/.claude/skills/quick-plan/SKILL.md

name, description, argument-hint

name	description	argument-hint
quick-plan	Create a planning document for a future homelab project. Use when the user wants to document ideas for future work without implementing immediately.	topic or feature to plan

Quick Plan Generator

Create a planning document for a future homelab infrastructure project. Plans are for documenting ideas and approaches that will be implemented later, not immediately.

Input

The user provides: $ARGUMENTS

Process

1. Understand the topic: Research the codebase to understand:

   • Current state of related systems
   • Existing patterns and conventions
   • Relevant NixOS options or packages
   • Any constraints or dependencies

2. Evaluate options: If there are multiple approaches, research and compare them with pros/cons.

3. Draft the plan: Create a markdown document following the structure below.

4. Save the plan: Write to docs/plans/<topic-slug>.md using a kebab-case filename derived from the topic.

Plan Structure

Use these sections as appropriate (not all plans need every section):

# Title

## Overview/Goal
Brief description of what this plan addresses and why.

## Current State
What exists today that's relevant to this plan.

## Options Evaluated (if multiple approaches)
For each option:
- **Option Name**
  - **Pros:** bullet points
  - **Cons:** bullet points
  - **Verdict:** brief assessment

Or use a comparison table for structured evaluation.

## Recommendation/Decision
What approach is recommended and why. Include rationale.

## Implementation Steps
Numbered phases or steps. Be specific but not overly detailed.
Can use sub-sections for major phases.

## Open Questions
Things still to be determined. Use checkbox format:
- [ ] Question 1?
- [ ] Question 2?

## Notes (optional)
Additional context, caveats, or references.

Style Guidelines

• Concise: Use bullet points, avoid verbose paragraphs
• Technical but accessible: Include NixOS config snippets when relevant
• Future-oriented: These are plans, not specifications
• Acknowledge uncertainty: Use "Open Questions" for unresolved decisions
• Reference existing patterns: Mention how this fits with existing infrastructure
• Tables for comparisons: Use markdown tables when comparing options
• Practical focus: Emphasize what needs to happen, not theory

Examples of Good Plans

Reference these existing plans for style guidance:

• docs/plans/auth-system-replacement.md - Good option evaluation with table
• docs/plans/truenas-migration.md - Good decision documentation with rationale
• docs/plans/remote-access.md - Good multi-option comparison
• docs/plans/prometheus-scrape-target-labels.md - Good implementation detail level

After Creating the Plan

1. Tell the user the plan was saved to docs/plans/<filename>.md
2. Summarize the key points
3. Ask if they want any adjustments before committing