Erk Planning Skill

When to Load

Load this skill when user mentions:

"update plan", "update the plan"

"modify the plan", "change the plan"

"edit the plan"

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

Check for

plan-saved-issue.marker

in session scratch:

erk

exec

marker

read

--session-id

<

session-id

>

plan-saved-issue

If found (exit code 0), invoke

/local:plan-update

with the marker content

If not found (exit code 1), ask user for issue number

Overview

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

PR 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. Plan Structure PR #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 pr dispatch 123 │ └── Comment #456789 (first comment, plan content):

Quick Reference Creating a Plan After writing a plan in plan mode:

Via slash command (recommended)

/erk:plan-save

Via CLI

erk exec plan-save --format display --session-id = "" Updating an Existing Plan When you need to modify a plan that's already saved to GitHub:

Via slash command

/local:plan-update 123

Via CLI

erk

exec

plan-update --plan-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

Fetch existing plan

(if not in local files):

gh

pr

view

123

--comments

--json

comments

Extract content from

plan-body

block in first comment.

Enter plan mode

and make modifications

Update the issue

:

/local:plan-update

123

Optionally add a comment

explaining what changed:

gh

pr

comment

123

--body

"Updated plan: added step 3 for edge case handling"

Plan Mode Integration

When exiting plan mode with an existing linked issue (e.g., from

.erk/impl-context//ref.json

), consider:

Update existing

If iterating on the same plan

Save as new

If this is a fresh plan unrelated to the linked issue

Implement directly

If changes are ready to code The plan-update command finds plan content from: --plan-path flag (explicit file path) Session scratch storage (via --session-id ) ~/.claude/plans/ directory (latest plan file) Related Commands Command Purpose /erk:plan-save Create new plan PR from current plan /local:plan-update Update existing plan /erk:plan-implement Save plan and immediately implement /erk:replan Analyze and recreate obsolete plan erk implement Implement a saved plan Resources references/ workflow.md - Complete update workflow with examples