/ralphex-plan

description: Create structured implementation plan in docs/plans/

Implementation Plan Creation

Create an implementation plan in `docs/plans/YYYYMMDD-<task-name>.md` with interactive context gathering.

Prerequisites: Verify CLI Installation

Check if ralphex CLI is installed (needed to execute the plan after creation):

which ralphex

**If not found**, inform user they'll need it to execute the plan:

• **macOS (Homebrew)**: `brew install umputun/apps/ralphex`
• **Linux (Debian/Ubuntu)**: download `.deb` from https://github.com/umputun/ralphex/releases
• **Linux (RHEL/Fedora)**: download `.rpm` from https://github.com/umputun/ralphex/releases
• **Any platform with Go**: `go install github.com/umputun/ralphex/cmd/ralphex@latest`

Proceed with plan creation regardless, but remind user to install before execution.

Step 0: Parse Intent and Gather Context

Before asking questions, understand what the user is working on:

1. **Parse user's command arguments** to identify intent:

• "add feature Z" / "implement W" → feature development
• "fix bug" / "debug issue" → bug fix plan
• "refactor X" / "improve Y" → refactoring plan
• "migrate to Z" / "upgrade W" → migration plan
• generic request → explore current work

2. **Launch Explore agent** (via Task tool with `subagent_type: Explore`) to gather relevant context based on intent:

**For feature development:**

• locate related existing code and patterns
• check project structure (README, config files, existing similar implementations)
• identify affected components and dependencies

**For bug fixing:**

• look for error logs, test failures, or stack traces
• find related code that might be involved
• check recent git changes in problem areas

**For refactoring/migration:**

• identify all files/components affected
• check test coverage of affected areas
• find dependencies and integration points

**For generic/unclear requests:**

• check `git status` and recent file activity
• examine current working directory structure
• identify primary language/framework from file extensions and config files

3. **Synthesize findings** into context summary:

• what work is in progress
• which files/areas are involved
• what the apparent goal is
• relevant patterns or structure discovered

Step 1: Present Context and Ask Focused Questions

Show the discovered context, then ask questions **one at a time** using the AskUserQuestion tool:

"Based on your request, I found: [context summary]"

**Ask questions one at a time (do not overwhelm with multiple questions):**

1. **Plan purpose**: use AskUserQuestion - "What is the main goal?"

• provide multiple choice with suggested answer based on discovered intent
• wait for response before next question

2. **Scope**: use AskUserQuestion - "Which components/files are involved?"

• provide multiple choice with suggested discovered files/areas
• wait for response before next question

3. **Constraints**: use AskUserQuestion - "Any specific requirements or limitations?"

• can be open-ended if constraints vary widely
• wait for response before next question

4. **Testing approach**: use AskUserQuestion - "Do you prefer TDD or regular approach?"

• options: "TDD (tests first)" and "Regular (code first, then tests)"
• store preference for reference during implementation
• wait for response before next question

5. **Plan title**: use AskUserQuestion - "Short descriptive title?"

• provide suggested name based on intent

After all questions answered, synthesize responses into plan context.

Step 1.5: Explore Approaches

Once the problem is understood, propose implementation approaches:

1. **Propose 2-3 different approaches** with trade-offs for each 2. **Lead with recommended option** and explain reasoning 3. **Present conversationally** - not a formal document yet

Example format:

I see three approaches:

**Option A: [name]** (recommended)
- How it works: ...
- Pros: ...
- Cons: ...

**Option B: [name]**
- How it works: ...
- Pros: ...
- Cons: ...

Which direction appeals to you?

Use AskUserQuestion tool to let user select preferred approach before creating the plan.

**Skip this step** if:

• the implementation approach is obvious (single clear path)
• user explicitly specified how they want it done
• it's a bug fix with clear solution

Step 2: Create Plan File

Check `docs/plans/` for existing files, then create `docs/plans/YYYYMMDD-<task-name>.md`:

Plan Structure

# [Plan Title]

## Overview
- Clear description of the feature/change being implemented
- Problem it solves and key benefits
- How it integrates with existing system

## Context (from discovery)
- Files/components involved: [list from step 0]
- Related patterns found: [patterns discovered]
- Dependencies identified: [dependencies]

## Development Approach
- **Testing approach**: [TDD / Regular - from user preference in planning]
- Complete each task fully before moving to the next
- Make small, focused changes
- **CRITICAL: every task MUST include new/updated tests** for code changes in that task
  - tests are not optional - they are a required part of the checklist
  - write unit tests for new functions/methods
  - write unit tests for modified functions/methods
  - add new test cases for new code paths
  - update existing test cases if behavior changes
  - tests cover both success and error scenarios
- **CRITICAL: all tests must pass before starting next task** - no exceptions
- **CRITICAL: update this plan file when scope changes during implementation**
- Run tests after each change
- Maintain backward compatibility

## Testing Strategy
- **Unit tests**: required for every task (see Development Approach above)
- **E2E tests**: if project has UI-based e2e tests (Playwright, Cypress, etc.):
  - UI changes → add/update e2e tests in same task as UI code
  - Backend changes supporting UI → add/update e2e t