erk-planning

Load this skill when user mentions:

• "update plan", "update the plan", "update issue"
• "modify the plan", "change the plan"
• "edit the issue", "update the issue"

When these triggers fire and a plan was saved in this session:

1. Check for plan-saved-issue.marker in session scratch:

```bash

erk exec marker read --session-id plan-saved-issue

```

1. If found (exit code 0), invoke /local:plan-update with the marker content
2. If not found (exit code 1), ask user for issue number

Erk-plans are GitHub issues that track implementation plans. They have a two-part structure:

• Issue body: Machine-readable metadata (timestamps, comment IDs, dispatch info)
• First comment: Human-readable plan content in a plan-body metadata block

This separation keeps metadata parseable while plan content remains readable.

```

Issue #123: "Add feature X [erk-plan]"

├── Body (metadata only):

│

│ created_at: 2025-01-05T12:00:00Z

│ created_by: username

│ plan_comment_id: 456789

│

│

│ ## Commands

│ - erk implement 123

│ - erk plan submit 123

│

└── Comment #456789 (first comment, plan content):

```

Creating a Plan Issue

After writing a plan in plan mode:

```bash

# Via slash command (recommended)

/erk:plan-save

# Via CLI

erk exec plan-save-to-issue --format display --session-id=""

```

Updating an Existing Plan Issue

When you need to modify a plan that's already saved to GitHub:

```bash

# Via slash command

/local:plan-update 123

# Via CLI

erk exec plan-update-issue --issue-number 123 --session-id=""

```

When to update vs create new:

| Scenario | Action |

| -------------------------------------------- | ---------------------------- |

| Minor corrections (typos, clarifications) | Update existing |

| Adding details discovered during exploration | Update existing |

| Plan is fundamentally wrong/obsolete | Create new via /erk:replan |

| Significant scope change | Create new, close old |

The Update Workflow

1. Fetch existing plan (if not in local files):

```bash

gh issue view 123 --comments --json comments

```

Extract content from plan-body block in first comment.

1. Enter plan mode and make modifications

1. Update the issue:

```bash

/local:plan-update 123

```

1. Optionally add a comment explaining what changed:

```bash

gh issue comment 123 --body "Updated plan: added step 3 for edge case handling"

```

When exiting plan mode with an existing linked issue (e.g., from .impl/issue.json), consider:

1. Update existing: If iterating on the same plan
2. Save as new: If this is a fresh plan unrelated to the linked issue
3. Implement directly: If changes are ready to code

The plan-update-issue command finds plan content from:

1. --plan-path flag (explicit file path)
2. Session scratch storage (via --session-id)
3. ~/.claude/plans/ directory (latest plan file)

| Command | Purpose |

| ----------------------- | --------------------------------------- |

| /erk:plan-save | Create new plan issue from current plan |

| /local:plan-update | Update existing plan issue |

| /erk:plan-implement | Save plan and immediately implement |

| /erk:replan | Analyze and recreate obsolete plan |

| erk implement | Implement a saved plan |

references/

• workflow.md - Complete update workflow with examples