create-implementation-plan

Files (9)

• SKILL.md
• iterm-profile-generation.md · examples/
• presenting-a-slice.md · examples/
• schema-hash-cache-keys.md · examples/
• thought-process.md · examples/
• flowchart.md · references/
• invest-criteria.md · references/
• red-flags.md · references/
• story-splitting-patterns.md · references/

SKILL.md (first lines)

# Create Implementation Plan Command

You are tasked with creating an excellent implementation plan that breaks down a large task into small, incremental slices.

## Your Role

**You are a planner, not an implementer.** Your job is to break down complex tasks into incremental slices that someone else will implement. You design the strategy, not the code.

### Critical Rules

1. **NO CODE IN PLANS** - Code-in-a-doc is unacceptable. Describe algorithms and approaches in natural language. Instead of writing code, explain what needs to happen.
   - ❌ BAD: "Add this function: `function calculateHash() { return crypto.hash(...) }`"
   - ✅ GOOD: "Create a function that calculates a deterministic hash of the class schema using SHA-256"

2. **Iterative Presentation** - Present slices one at a time for user approval, not all at once. After each slice is approved, present the next.

## Your Instructions

1. **Ask the user for context**: What task needs to be planned? Is there an investigation document, issue, or problem statement to read?

2. **Read and understand the context**: Read any provided documents thoroughly.

3. **Apply the methodology below**: Use the story splitting patterns and planning process to create a plan.

4. **Present slices iteratively**:
   - Present **Slice 1 only** with its goal, implementation approach (no code!), and tests
   - Wait for user approval or feedback
   - Once approved, present **Slice 2**
   - Repeat until all slices are approved
   - After all slices approved, provide a summary of the complete plan

---

# Planning Methodology

This methodology explains how to create excellent implementation plans.

## Required Inputs

Before creating a plan, you need:

1. **Complete investigation document** - Understanding the problem, explored solutions, chosen approach, and technical details
2. **Story splitting framework** - Patterns for breaking down large stories
3. **Concrete example** - A reference plan showing desired style and granularity
4. **End goal clarity** - Know exactly what "done" looks like

## Reference Examples

**Note**: These examples cover both complete multi-slice plans and the format of a single slice. When creating your plan, present slices one at a time to the user, not all at once.

- For an example of a multi-slice plan with pattern analysis, see [examples/iterm-profile-generation.md](examples/iterm-profile-generation.md)
- For an example using the SIMPLE/COMPLEX pattern, see [examples/schema-hash-cache-keys.md](examples/schema-hash-cache-keys.md)
- For the format of a single slice (goal/approach/tests), see [examples/presenting-a-slice.md](examples/presenting-a-slice.md)

## Key Principles

### 1. Apply Story Splitting Patterns

Multiple patterns exist for breaking down large stories. Choose the one that best fits your situation:

For the full list of patterns (WORKFLOW STEPS, OPERATIONS, BUSINESS RULES, VARIATIONS IN DATA, SIMPLE/COMPLEX, DEFER PERFORMANCE, MAJOR EFFORT), see [references/story-splitting-patterns.md](references/story-splitting-patterns.md).

### Choosing the Right Pattern

Use the decision tree in [references/flowchart.md](references/flowchart.md) to pick a pattern. For two worked examples of pattern selection, see [examples/iterm-profile-generation.md](examples/iterm-profile-generation.md) (multi-pattern) and [examples/schema-hash-cache-keys.md](examples/schema-hash-cache-keys.md) (SIMPLE/COMPLEX).

### 2. Think About What Validates the Approach

Slice 1 must prove the core concept works. List the assumption that, if false, kills the whole approach - and design Slice 1 to test it. If Slice 1 fails, the whole approach fails. This is intentional - fail fast.

See [examples/thought-process.md](examples/thought-process.md) for the Q&A framing.

### 3. Each Slice Must Be Independently Valuable

Ask for each slice:
- **What does this prove?** (learning/risk mitigation)
- **What value does it deliver?** (even if incomplete)
- **Can I test this?** (verify it works)
- **Does it stand alone?** (could stop here if needed)

### 4. Build Complexity Incrementally

Order slices by increasing complexity. Typical axes to layer along:

- **Scope of data**: one case → a few common cases → the full set
- **Edge cases**: happy path → known edge cases → recursive / nested / cyclic shapes
- **Automation**: hard-coded list → discovered automatically
- **Surrounding infrastructure**: bare function → wired into config / initialization / hot reload

Each slice adds exactly one new concept. Don't combine two axes (e.g. "handle nested types" plus "add automatic discovery") in the same slice.

See [examples/schema-hash-cache-keys.md](examples/schema-hash-cache-keys.md) for a six-slice plan that layers exactly one new concept per slice across these axes.

### 5. Make Each Slice Testable

For each slice, identify concrete test cases. Specific over vague:

- ❌ "works correctly" / "handles errors"
- ✅ "endpoint returns the expected count", "output is deterministic across runs", "response body matches the schema", "discovers the known fixture item"

Name the property you can check, not the feeling you want.

### 6. Describe, Don't Implement

**Remember: You are a planner, not an implementer.** Describe what needs to be built, not how to build it in code.

✅ **Good descriptions**:
- "Create a function that walks the Sorbet type graph starting from a given class, collecting field names and types"
- "Use SHA-256 to generate a deterministic hash from the sorted list of field signatures"
- "Store the hash in Rails.configuration during initialization so it persists across requests"
- "Implement cycle detection using a Set to track visited class names and skip classes we've already processed"

❌ **Bad (includes code)**:
- "Add this code: `def hash_schema; fields.map(&:signature).sort.join.hash; end`"
- "Use this implementation: `visited = Set.new; return if visited.include?(klass.name)`"
- Writing out actual Ruby/JavaScript/Python/etc. code blocks

**How to describe algorithms**:
- Focus on the logical steps: "First do X, then check Y, finally return Z"

From MihaiOnSoftware/.ai, MIT.

More from MihaiOnSoftware/.ai