---
description: Replan an existing erk-plan issue against current codebase state
argument-hint: <issue-number-or-url>
---

# /erk:replan

Recomputes existing erk-plan issue(s) against the current codebase state, creating a new plan and closing the original(s).

Supports consolidating multiple plans into a single unified plan.

## Usage

```bash
/erk:replan 2521                          # Single plan replan
/erk:replan https://github.com/owner/repo/issues/2521
/erk:replan 123 456 789                   # Consolidate multiple plans
```

---

## Agent Instructions

### Step 1: Parse Issue References

Split `$ARGUMENTS` on whitespace. For each argument:

- If numeric (e.g., `2521`), use directly as issue number
- If URL (e.g., `https://github.com/owner/repo/issues/2521`), extract the number from the path

Store all issue numbers in a list. Set `CONSOLIDATION_MODE=true` if multiple issues provided.

If no argument provided, ask the user for the issue number.

### Step 2: Validate All Plans (Parallel if Multiple)

For each issue number, fetch and validate:

```bash
erk exec get-issue-body <number>
```

This returns JSON with `{success, issue_number, title, body, state, labels, url}`. Store each issue's title.

Validate each issue:

1. Issue exists
2. Issue has `erk-plan` label
3. Track if issue has `erk-learn` label (for Step 7)

Store whether ANY issue has the `erk-learn` label. Set `IS_LEARN_PLAN=true` if any source issue has this label.

If any issue is not an erk-plan issue, display error and abort:

```
Error: Issue #<number> is not an erk-plan issue (missing erk-plan label).
```

If any issue is already closed, display warning but continue:

```
Warning: Issue #<number> is already closed. Proceeding with replan anyway.
```

### Step 2.5: Extract Objective Issue

For each validated plan, extract the `objective_issue` metadata:

```bash
erk exec get-plan-metadata <number> objective_issue
```

Store the objective issue number(s) for later use when saving the new plan.

**For single plan:** Use the `objective_issue` if present.

**For consolidation mode:**

- If all plans share the same `objective_issue`, use it
- If plans have different `objective_issues`, warn the user and ask which to use
- If only some plans have `objective_issues`, use the one(s) that exist

### Step 3: Plan Content Fetching (Delegated to Step 4)

Plan content is fetched by each Explore agent in Step 4, not in the main context.
This avoids dumping large plan bodies into the main conversation.

Skip to Step 4.

### Step 4: Deep Investigation

Use the Explore agent (Task tool with subagent_type=Explore) to perform deep investigation of the codebase.

**If CONSOLIDATION_MODE:**

Launch parallel Explore agents (one per plan, using `run_in_background: true`), each investigating:

- Plan items and their current status
- Overlap potential with other plans being consolidated
- File mentions and their current state

**For each plan (parallel or sequential):**

#### 4a: Fetch Plan Content (Agent's First Action)

Each Explore agent MUST fetch its issue's plan content as its first action. This keeps the raw plan content inside the agent's context instead of the main conversation.

**Fetch command:**

```bash
gh issue view <number> --comments --json comments --jq '.comments[0].body'
```

**Parse the plan content:**

1. Look for the `<!-- erk:metadata-block:plan-body -->` metadata block in the first comment
2. Extract the plan content from within the `<details>` block
3. If no `plan-body` metadata block is found in the first comment, check the issue body directly (handles cases like #6431 where content is in the body)

**If no plan content found:**

Return an error to the main agent:

```
Error: No plan content found in issue #<number>. Expected plan-body metadata block in first comment or issue body.
```

The agent should fail early if it cannot fetch the plan content, rather than proceeding with incomplete information.

#### 4b: Check Plan Items Against Codebase

For each implementation item in the plan (now fetched in 4a):

- Search for relevant files, functions, or patterns
- Determine status: **implemented**, **partially implemented**, **not implemented**, or **obsolete**

Build a comparison table showing:

| Plan Item | Current Status | Notes |
| --------- | -------------- | ----- |
| ...       | ...            | ...   |

#### 4c: Deep Investigation (MANDATORY)

Go beyond the plan items to understand the actual implementation:

1. **Data Structures**: Find all relevant types, dataclasses, and their fields
2. **Helper Functions**: Identify utility functions and their purposes
3. **Lifecycle & State**: Understand how state flows through the system
4. **Naming Conventions**: Document actual names used (not guessed names)
5. **Entry Points**: Map all places that trigger the relevant functionality
6. **Configuration**: Find config options, defaults, and overrides

#### 4d: Document Corrections and Discoveries

Create two lists per plan:

1. **Corrections to Original Plan**: Wrong assumptions, incorrect names, outdated information
2. **Additional Details**: Implementation specifics, architectural insights, edge cases

### Step 4e: Consolidation Analysis (CONSOLIDATION_MODE only)

If consolidating multiple plans:

1. **Identify Overlap**: Find items that appear in multiple plans
2. **Merge Strategy**: Determine how to combine overlapping items
3. **Dependency Ordering**: Order items by dependency across all plans
4. **Attribution Tracking**: Track which items came from which plan

### Step 4f: Wait for All Background Investigations (CRITICAL)

**BEFORE proceeding to Step 5 or Step 6, you MUST wait for ALL background agents to complete.**

If you launched agents with `run_in_background: true`:

1. **Check agent status**: Use TaskOutput with `block: true` to wait for each background agent
2. **Collect all results**: Do not proceed until every agent has returned its findings
3. **Synthesize findings**: Combine results from all agents into a unified investigation summary

**Why this matters:**

- Background agents may discover critical corrections or implementation details
- Creating the plan before investigations complete leads to incomplete or inaccurate plans
- The consolidated plan quality depends on having ALL investigation data

**How to wait:**

For each background agent task_id, use TaskOutput tool with:

- `block: true` to wait for completion
- `timeout: 600000` (10 minutes)

Then read the agent's findings from the output.

Only after ALL agents have completed should you proceed to Step 5.

### Step 5: Post Investigation to Original Issue(s)

Before creating the new plan, post investigation findings to each original issue as a comment:

```bash
gh issue comment <original_number> --body "## Deep Investigation Notes (for implementing agent)

### Corrections to Original Plan
- [List corrections discovered]

### Additional Details Not in Original Plan
- [List new details discovered]

### Key Architectural Insights
- [List important discoveries]"
```

If consolidating, include note:

```
Note: This plan is being consolidated with #<other_numbers> into a unified plan.
```

### Step 6: Create New Plan (Always)

**Always create a new plan issue**, regardless of implementation status.

#### 6a: Gather Investigation Context

Before entering Plan Mode, collect all investigation findings from Steps 4-5:

1. **Investigation status per plan**: Completion percentages (e.g., "4/11 items implemented")
2. **Specific discoveries**: File paths, line numbers, commit hashes, PR numbers
3. **Corrections found**: What the original plan(s) got wrong
4. **Codebase evidence**: Actual function names, class signatures, config values

For consolidation mode, also gather:

- **Overlap analysis**: Which items appeared in multiple plans
- **Merge decisions**: Why items were combined or kept separate
- **Attribution map**: Which source plan contributed each item

#### 6b: Enter Plan Mode with Full Context

Use EnterPlanMode to create an updated plan.

**CRITICAL:** The plan content MUST include the investigation findings, not just summarize them. Each implementation step should have:

- **Specific file paths** (e.g., `docs/learned/architecture/gateway-inventory.md:45`)
- **What to change** (not "update X" but "add entry for CommandExecutor with ABC at line 105")
- **Evidence** (commit hashes, PR numbers, current line numbers)
- **Verification criteria** (how to confirm the step is complete)

**Anti-pattern (sparse):**

```
1. Update gateway documentation
2. Add missing tripwires
```

**Correct pattern (comprehensive):**

```
1. **Update gateway-inventory.md** (`docs/learned/architecture/gateway-inventory.md`)
   - Add missing entries: CommandExecutor (abc.py:105), PlanDataProvider (abc.py:142)
   - Fix import paths at lines 45, 67 (change `erk.gateways.` → `erk.gateway.`)
   - Verification: All gateways in `src/erk/gateway/` have entries
```

---

#### Single Plan Format

```markdown
# Plan: [Updated Title]

> **Replans:** #<original_issue_number>

## What Changed Since Original Plan

- [List major codebase changes that affect this plan]

## Investigation Findings

### Corrections to Original Plan

- [List any wrong assumptions or incorrect names]

### Additional Details Discovered

- [List implementation specifics not in original plan]

## Remaining Gaps

- [List items from original plan that still need implementation]

## Implementation Steps

1. [Updated step 1]
2. [Updated step 2]
```

---

#### Consolidated Plan Format (CONSOLIDATION_MODE)

```markdown
# Plan: [Unified Title]

> **Consolidates:** #123, #456, #789

## Source Plans

| #   | Title              | Items Merged |
| --- | ------------------ | ------------ |
| 123 | [Title from issue] | X items      |
| 456 | [Title from issue] | Y items      |
| 789 | [Title from issue] | Z items      |

## What Changed Since Original Plans

- [List major codebase changes affecting any of the plans]

## Investigation Findings

### Corrections to Original Plans

- **#123**: [corrections]
- **#456**: [corrections]
- **#789**: [corrections]

### Additional Details Discovered

- [Combined implementation specifics]

### Overlap Analysis

- [Items that appeared in multiple plans, now merged]

## Remaining Gaps

- [Combined items that still need implementation]

## Implementation Steps

1. [Step] _(from #123)_
2. [Merged step] _(from #123, #456)_
3. [Step] _(from #456)_
4. [Step] _(from #789)_

## Attribution

Items by source:

- **#123**: Steps 1, 2
- **#456**: Steps 2, 3
- **#789**: Step 4
```

---

### Step 7: Save and Close

After the user approves the plan in Plan Mode:

1. Exit Plan Mode
2. Run `/erk:plan-save` to create the new GitHub issue:
   - **If any source plan(s) had `erk-learn` label** (`IS_LEARN_PLAN=true`): Add `--plan-type=learn` to the command
   - **If the source plan(s) had an `objective_issue`**: Pass it with `--objective-issue=<objective_number>`
   - **If consolidating with conflicting objectives**: Use the objective chosen by the user in Step 2.5
   - **Otherwise**: Run `/erk:plan-save` without flags
3. **If `--objective-issue` was used**, verify the link was saved correctly:
   ```bash
   erk exec get-plan-metadata <new_issue_number> objective_issue
   ```
   If the objective link is missing, warn the user that the plan may not be linked to its objective.
4. **If CONSOLIDATION_MODE** (multiple plans consolidated), add the `erk-consolidated` label:
   ```bash
   gh issue edit <new_issue_number> --add-label "erk-consolidated"
   ```
   This prevents the consolidated plan from being re-consolidated by `/local:replan-learn-plans`.
5. Close original issue(s) with comment linking to the new one:

**Single plan:**

```bash
gh issue close <original_number> --comment "Superseded by #<new_number> - see updated plan that accounts for codebase changes."
```

**Consolidated plans:**

```bash
gh issue close 123 --comment "Consolidated into #<new_number> with #456, #789"
gh issue close 456 --comment "Consolidated into #<new_number> with #123, #789"
gh issue close 789 --comment "Consolidated into #<new_number> with #123, #456"
```

Display final summary:

**Single plan:**

```
✓ Created new plan issue #<new_number>
✓ Closed original issue #<original_number>

Next steps:
- Review the new plan: gh issue view <new_number>
- Submit for implementation: erk plan submit <new_number>
```

**Consolidated plans:**

```
✓ Created consolidated plan issue #<new_number>
✓ Closed original issues: #123, #456, #789

Source plans consolidated:
- #123: [title]
- #456: [title]
- #789: [title]

Next steps:
- Review the consolidated plan: gh issue view <new_number>
- Submit for implementation: erk plan submit <new_number>
```

---

## Error Cases

| Error                    | Message                                                                       |
| ------------------------ | ----------------------------------------------------------------------------- |
| Issue not found          | `Error: Issue #<number> not found.`                                           |
| Not an erk-plan          | `Error: Issue #<number> is not an erk-plan issue (missing erk-plan label).`   |
| No plan content          | `Error: No plan content found in issue #<number>.`                            |
| GitHub CLI not available | `Error: GitHub CLI (gh) not available. Run: brew install gh && gh auth login` |
| No network               | `Error: Unable to reach GitHub. Check network connectivity.`                  |

---

## Important Notes

- **DO NOT implement the plan** - This command only creates an updated plan
- **DO NOT skip codebase analysis** - Always verify current state before replanning
- **Use Explore agent** for comprehensive codebase searches (Task tool with subagent_type=Explore)
- **Parallel investigation** for multiple plans (run_in_background: true)
- Original issue(s) closed only after the new plan is successfully created
- The new plan references all original issue(s) for traceability
