plan-ralphex

name	plan-ralphex
description	Create an implementation plan for a new feature, refactor, or fix. Guides an interactive design discussion and produces a structured plan document.
allowed-tools	Read, Write, Edit, Glob, Grep, Agent, Skill, AskUserQuestion, Bash(git rev-parse:*)

Create Implementation Plan

Create a structured implementation plan in docs/plans/ following the project's established format. The plan captures design decisions, file changes, and task breakdown before any code is written.

Context

• Repo root: !git rev-parse --show-toplevel 2>/dev/null || pwd

Working directory

All docs/plans/ paths in this skill (the new plan file, samples cross-reference, completed plans for convention discovery, the eventual move-to-completed step) are relative to Repo root from Context. The cwd may be a subdirectory — prefix Repo root when calling Read/Write/Glob/Grep. Writing docs/plans/YYYY-MM-DD-slug.md from a subdirectory creates the file in the wrong place silently.

Important

• This is an interactive process — ask clarifying questions, propose alternatives, and iterate on the design with the user before writing the final plan
• Do NOT write code or make changes to source files — this skill only produces a plan document
• The plan must be detailed enough that it can be executed without re-reading the original discussion

Step 1: Understand the request

Read the user's description of what they want. If the request is vague or ambiguous, ask clarifying questions before proceeding.

Step 2: Research the codebase

Explore relevant files to understand:

• Current architecture and patterns
• Which files need modification
• Related existing functionality
• Test patterns in use

Read all sample plans from ~/.claude/skills/plan-ralphex/samples/ to learn the established format and level of detail. Then read 2–3 completed plans from docs/plans/completed/ (if any exist) to pick up project-specific conventions.

Step 3: Interactive design discussion

Present your understanding of the problem and a proposed approach. Discuss with the user:

• Design trade-offs and alternatives
• Edge cases and constraints
• UI/UX decisions (if applicable)
• Scope — what's in and what's out

Iterate until the user is satisfied with the approach. Do not rush to write the plan.

Step 4: Write the plan

Create the plan file at docs/plans/YYYY-MM-DD-short-slug.md using today's date. Follow this structure:

# Title

## Overview

One paragraph describing what this plan accomplishes and why.

## Context

- Files involved:
  - Modify: `path` — brief description
  - Create: `path` — brief description
- Related patterns: existing code/patterns this builds on
- Dependencies: external requirements (if any)

## Development Approach

- Testing approach: Regular (code first, then tests)
- Complete each task fully before moving to the next
- **CRITICAL: every task MUST include new/updated tests**
- **CRITICAL: all tests must pass before starting next task**

## Design Notes

Document key design decisions, trade-offs, and rationale.
Use bold headers for each topic. Include enough detail that
the reasoning is clear without re-reading the discussion.

**No defensive fallbacks**: Do not design fallback values that mask invalid data (e.g. showing "?" for null ages). Trust input correctness — let invalid values surface as visible `null` or runtime errors rather than silently producing plausible-looking wrong output.

## Implementation Steps

### Task N: Short title

**Files:**
- Modify: `path`
- Create: `path`

- [ ] Step description
- [ ] Step description
- [ ] Write/update tests for ...
- [ ] Run project test suite — must pass before next task

### Task N+1: Verify acceptance criteria

- [ ] Manual test: ...
- [ ] Run full test suite: `npm test`
- [ ] Run linter: `npm run lint`

### Task N+2: Update documentation

- [ ] Update README.md if user-facing behavior changed
- [ ] Update CLAUDE.md if internal patterns changed
- [ ] Move this plan to `docs/plans/completed/`

Step 5: Iterative review with the user

After writing the plan to disk, invoke /plannotator-annotate on the plan file so the user can review and annotate it interactively.

1. Run /plannotator-annotate docs/plans/<plan-file>.md
2. Address all annotation feedback by editing the plan file
3. Run /plannotator-annotate again on the updated plan
4. Repeat until the user approves the plan with no further annotations

Do NOT skip this step or substitute it with a text-based "any changes?" question.

Completion

The end goal of this skill is a plan document in docs/plans/. Once the user approves the plan (no more annotations) and it is written to disk, the skill is done. Do NOT offer to execute the plan, start implementation, or invoke any other skill (e.g. ralphex) to carry out the plan.