---

name: implementation-plan-creator description: Create feature implementation plans before development. Captures requirements, acceptance criteria, non-goals, risks, and implementation complexity in structured markdown. Use when starting a new feature to ensure scope clarity and implementation guidance. license: MIT allowed-tools: Bash(git:) Read Bash(ls:) metadata: generated-at: "2026-01-09T00:00:00Z" group: "development" category: "planning" difficulty: "intermediate" step-count: "3"

Implementation Plan Creator

What You'll Do

• 📋 Gather planning details (scope, requirements, non-goals, risks, and implementation complexity)
• ✍️ Generate a structured markdown implementation plan file
• ✅ Ensure the plan lives in a plans/ directory with proper naming convention

---

Concept Introduction

An implementation plan is a specification-driven markdown document that captures everything needed to develop a feature: what the feature does, what success looks like, how it will be built, and who will build it. Creating a clear implementation plan before coding ensures:

• Scope clarity: Everyone understands what's being built, why, and what's NOT being built
• Specification completeness: Feature requirements and acceptance criteria are documented upfront
• Risk awareness: Potential challenges and dependencies are identified early
• Implementation guidance: Approach and technical considerations guide development decisions
• Complexity clarity: Key factors affecting implementation are documented upfront
• Progress tracking: Acceptance criteria serve as a checklist during development

Implementation plans live in a plans/ directory with filenames following the pattern: YYYY-MM-DD-feature-short-name.md

Key sections: Overview → Requirements → Non-Goals → Acceptance Criteria → Implementation Complexity → Implementation → Risks → Dependencies → References

---

When to Use This Skill

Use this skill when you're:

• ✅ Starting development on a new feature
• ✅ Adding new capability or user-facing functionality
• ✅ Need to document scope, requirements, and success criteria before coding

Do NOT use if you're:

• ❌ Fixing bugs or issues
• ❌ Completing technical chores (refactoring, dependencies, infrastructure)
• ❌ Making minor fixes or documentation updates
• ❌ Working on quick, well-defined tasks without planning needs

Decision Point: Is this a new feature or user-facing capability?

• YES → Proceed to Phase 1. You're in the right place.
• NO → This skill is not a good fit. Focus on the work without a plan.

---

Phase 1: 📋 ANALYSIS - Understand the Feature

What you're doing: Gathering the information needed to create a comprehensive feature implementation plan.

Decision Point: How much detail do you already have?

• Full details (requirements, risks, implementation approach) → Skip to Phase 2 to create the plan directly.
• Partial info (some details missing) → Work through Phase 1 sections to fill gaps.
• High-level only (just the idea) → Work through Phase 1 comprehensively to understand the feature fully.

For guidance on what questions to ask at each mode, see references/agent-modes.md.

Now clarify these aspects of your feature:

1. Title & Overview

Define what you're building:

• Title: Short, clear name (e.g., "Add dark mode toggle", "Implement two-factor authentication", "Create user profile editor")
• Overview: 1-2 sentences explaining what the feature does and why it matters

Example:

CopyTitle: Add Dark Mode Toggle
Overview: Enable users to switch between light and dark themes with preference persistence across sessions. This improves usability for users working in low-light environments.

2. Requirements

List 3-5 specific requirements that must be true:

• What capabilities does this feature provide?
• What must work across different scenarios?
• What systems or data does it interact with?

Example requirements:

Copy- Users can toggle dark mode from Settings page
- Dark mode preference persists across browser sessions
- All UI elements remain readable in both light and dark modes
- Dark mode works consistently on mobile and desktop
- Theme applies instantly without page reload

3. Acceptance Criteria

Define testable criteria that verify the feature is complete:

• What will be true when this feature is done?
• What can be tested to verify success?
• What edge cases should be handled?

4. Non-Goals

Clarify what will NOT be built to keep scope focused.

5. Risks & Mitigations

Identify potential issues and how you'll address them.

6. Dependencies

List external services, libraries, approvals, or team dependencies required.

7. Implementation Complexity

Document factors affecting implementation complexity (dependencies, integration points, testing needs, potential challenges).

Verification Checklist:

• Feature title is clear and descriptive
• Overview explains the feature (what and why)
• 3-5 requirements documented
• Non-goals are explicit
• Acceptance criteria are testable
• Risks and mitigations identified
• Dependencies listed
• Implementation complexity factors documented

✅ PHASE 1 COMPLETE

All items checked? Great! You're ready for Phase 2. Your feature is well-understood and scoped. Now you'll create the actual implementation plan file.

---

Phase 2: ✍️ COMPOSITION - Create the Implementation Plan

What you're doing: Generating the markdown implementation plan file in the plans/ directory with proper formatting and structure.

File Creation

Generate a markdown file with:

• Filename: YYYY-MM-DD-feature-short-name.md (e.g., 2026-01-09-dark-mode-toggle.md)
• Location: plans/ directory (created automatically if needed)
• Format: Markdown with sections below

Implementation Plan Template Structure

Copy# [Feature Title]

## Overview
[What the feature does and why it matters - 1-2 sentences]

## Requirements
- Requirement 1
- Requirement 2
- Requirement 3
- Requirement 4
- Requirement 5

## Non-Goals
- Non-goal 1
- Non-goal 2
- Non-goal 3

## Acceptance Criteria
- [ ] Acceptance criterion 1
- [ ] Acceptance criterion 2
- [ ] Acceptance criterion 3
- [ ] Acceptance criterion 4
- [ ] Acceptance criterion 5

## Implementation Complexity
**Factors:** [Key factors affecting complexity - dependencies, integration points, testing scope, known challenges]

## Implementation

### Approach
[High-level strategy and technology choices]

### Implementation Steps
1. **[Step title]** - `path/to/file.ts`
   - What to do and why
   - Suggested code snippet based on existing codebase patterns:
   ```typescript
   // Example implementation

1. [Step title] - path/to/file2.ts
   • What to do and why
   • Suggested code snippet based on existing codebase patterns:

   Copy// Example implementation
   

Risks

• Risk 1
  • Mitigation: [How to address]
• Risk 2
  • Mitigation: [How to address]

Dependencies

• Dependency 1 (version X)
• Dependency 2 (version Y)
• External requirement (description)

References

[Links to relevant documentation, issues, or related code]

Copy
### Creation Steps

1. **Prepare directory** - Ensure `plans/` directory exists
   ```bash
   ./scripts/ensure-plans-dir.sh

1. Generate filename - Use today's date + short feature name

   • Today's date: YYYY-MM-DD format
   • Feature short name: 2-4 words, lowercase, hyphenated
   • Example: 2026-01-09-user-authentication.md

2. Populate sections - Fill in each section from Phase 1 analysis

   • Keep descriptions concise
   • Use checkboxes for criteria
   • Be specific about file modifications

Verification Checklist:

• File created in plans/ directory
• Filename follows correct pattern
• All required sections present
• Requirements are specific
• Acceptance criteria are testable
• Implementation notes are clear
• No placeholder text in any section

✅ PHASE 2 COMPLETE

All items checked? Excellent! Your implementation plan markdown is written and structured. Now you'll verify it's complete and ready for use.

---

Phase 3: ✅ VALIDATION - Finalize the Plan

What you're doing: Verifying the implementation plan is complete, clear, and ready for development.

Quality Checks

1. Completeness

   • All sections filled in (no "TBD" or empty sections)
   • Requirements and acceptance criteria are specific
   • Implementation notes provide actionable direction

2. Clarity

   • Title clearly describes what's being built
   • Description can be understood by someone unfamiliar with the work
   • Acceptance criteria are unambiguous

3. Actionability

   • Implementation notes identify specific files to modify
   • Approach is clear enough to guide development
   • Challenges and mitigations are documented

4. File Structure

   • File is in plans/ directory
   • Filename matches convention: YYYY-MM-DD-feature-short-name.md
   • Markdown is properly formatted

Decision Point: Is the plan ready?

• YES (all validation checks pass) → Plan is complete and ready to use
• NO (missing sections or unclear requirements) → Return to Phase 1 or 2 to refine

When the plan is ready:

• Share with team/stakeholders for feedback
• Use as reference while implementing
• Check off acceptance criteria during development
• Close the plan when work is complete

✅ PHASE 3 COMPLETE

All quality checks passed? Perfect! Your implementation plan is complete, validated, and ready for development. You have a clear roadmap for building this feature with documented requirements, success criteria, estimated effort, and identified risks.

---

Phase 4: 🎯 POST-EXECUTION - Verify Best Practices

What you're doing: Validating the implementation plan against best practices before it's ready for use.

After completing Phase 3, verify the plan follows these best practices:

Best Practices Checklist

• Specific, not vague - Requirements and criteria use concrete language ("Users can...", "The button will..."), not "system should improve"
• Non-goals are explicit - At least 3 things clarified as NOT being built
• Risks identified - Every risk has a documented mitigation strategy
• Complexity factors documented - Key factors affecting implementation are clearly explained
• Implementation is actionable - Each step identifies specific files and includes code patterns
• One feature per plan - Scope is focused, not trying to build multiple features
• No placeholders - No "TBD", "[example]", or incomplete sections
• Acceptance criteria are testable - Each criterion can be verified without ambiguity
• Dependencies are listed - All external requirements, libraries, and approvals documented

Decision: Are all best practices met?

• YES → Plan is complete, validated, and ready for development
• NO → Return to appropriate phase and refine before proceeding

✅ PHASE 4 COMPLETE

All best practices validated? Excellent! Your implementation plan meets quality standards and is ready to guide development.

---

Reference Section: What Goes In Each Part

Requirements (capabilities the feature must provide) vs. Acceptance Criteria (testable conditions proving success)

• Requirements: Capability-focused ("Users can toggle dark mode")
• Acceptance Criteria: Test-focused ("[ ] Toggle button works and saves preference")

Implementation section: Include approach (strategy and tech choices), then step-by-step implementation steps. Each step should have: file path, what to do and why, and suggested code snippet based on reading the codebase patterns matching your feature.

---

Examples

See references/examples.md for detailed examples and tips.

Decision Point: Do you need to see examples before writing your plan?

• YES → Review the examples file to understand structure and patterns.
• NO → Skip to Best Practices or LLM Output Format sections.

---

Best Practices

Do: Be specific, keep it focused (one feature per plan), define non-goals explicitly, identify risks with mitigations, document implementation complexity factors.

Don't: Use vague language, skip non-goals or risks, leave placeholders, over-engineer the plan (aim for 1-2 pages).

---

LLM Output Format

When generating an implementation plan markdown file, use this exact structure:

Copy# [Feature Title]

## Overview
[What the feature does and why it matters - 1-2 sentences]

## Requirements
- [Specific requirement 1]
- [Specific requirement 2]
- [Specific requirement 3]
- [Specific requirement 4]
- [Specific requirement 5]

## Non-Goals
- [What will NOT be built - justification]
- [What's deferred to future - why]
- [What's explicitly out of scope - rationale]

## Acceptance Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]
- [ ] [Testable criterion 4]
- [ ] [Testable criterion 5]

## Implementation Complexity
**Factors:** [Key factors affecting complexity - dependencies, integration points, testing scope, known challenges]

## Implementation

### Approach
[High-level strategy and technology choices]

### Files to Create/Modify
- `path/to/file1.ts` (description of change)
- `path/to/file2.tsx` (description of change)

## Risks
- Risk: [Description]
  Mitigation: [How to address]
- Risk: [Description]
  Mitigation: [How to address]

## Dependencies
- [Dependency name and version if applicable]
- [External service or approval required]
- [Team or infrastructure dependency]

## References
[Links or related information]

See references/examples.md for complete examples showing good vs. poor patterns and detailed guidance on each section.

---

Agent Behavior Guidelines

For guidance on operating modes, clarification questions, and when to ask for more information, see references/agent-modes.md.

---

Preconditions

Before using this skill:

• ✅ Git repository exists (or local project directory)
• ✅ plans/ directory will be created automatically if it doesn't exist
• ✅ You're working on a new feature (not a bug fix or chore)
• ✅ You have a clear understanding of what the feature should do
• ✅ You have initial thoughts on requirements and success criteria

---

Quick Reference

File naming: YYYY-MM-DD-feature-short-name.md (e.g., 2026-01-09-dark-mode-toggle.md) in plans/ directory

Template order: Title → Overview → Requirements → Non-Goals → Acceptance Criteria → Implementation Complexity → Implementation (Approach + Step-by-Step Steps with Code) → Risks → Dependencies → References

Key point: Be specific, define non-goals explicitly, identify risks with mitigations, document implementation complexity factors. See references/agent-modes.md for operating modes and clarification questions.