Plot: Create Idea

Create a plan for review: idea branch, plan file, and draft PR.

Input: $ARGUMENTS in the format <slug>: <title description>

Example: /plot-idea sse-backpressure: Handle SSE client disconnects gracefully

Setup

Add a ## Plot Config section to the adopting project's CLAUDE.md :

Plot Config

• Project board: <your-project-name> (#<number>) <!-- optional, for gh pr edit --add-project -->
• Branch prefixes: idea/, feature/, bug/, docs/, infra/
• Plan directory: docs/plans/
• Active index: docs/plans/active/
• Delivered index: docs/plans/delivered/

Model Guidance

Steps Min. Tier Notes

1. Parse Input Small String parsing

2. Pre-flight Checks Small (hard gate), Mid (soft warning) Slug collision is mechanical; title similarity needs mid-tier

3-8. Create Branch through Summary Small Git/gh commands, templates, file ops

The entire skill is small-model capable except the soft duplicate warning (title similarity in step 2).

1. Parse Input

If $ARGUMENTS is empty or missing:

• Look at the conversation context for clues about what the user wants to plan

• If obvious, propose: "It looks like you want to plan <slug>: <title> . Shall I proceed?"

• Otherwise ask: "What's the idea? Usage: /plot-idea <slug>: <title> "

Extract slug and title from $ARGUMENTS :

• Everything before the first : is the slug (trimmed)

• Everything after is the title (trimmed)

• If no : found, treat the entire input as the slug and ask for a title

• Slug must match [a-z0-9-]+ (lowercase letters, digits, hyphens only). If it doesn't, ask the user to fix it rather than silently normalizing

Batch Mode

If the user provides multiple slugs (comma-separated or as a list), or asks to create multiple plans "in batch" or "together":

• Parse each <slug>: <title> pair

• Create a single branch: idea/batch-<first-slug> (or a name the user provides)

• Create all plan files on that branch, each with its own file and active symlink

• Create a single PR titled "Plan: , , ..."

The plans are still independent after approval — /plot-approve processes each slug separately.

Detection: Multiple : entries in $ARGUMENTS , words like "batch"/"together"/"all at once" in conversation context, or an explicit list of slugs.

2. Pre-flight Checks

• Warn if working tree has uncommitted changes (offer to stash)

• Verify gh auth status has project scope

• Check that branch idea/<slug> does not already exist (if it does, ask whether to check it out or pick a new name)

• Duplicate detection:

• ls docs/plans/active/ 2>/dev/null

• gh pr list --json headRefName --jq '.[].headRefName' | grep '^idea/' to find existing plans and idea branches

• Hard gate: if a plan with the identical slug already exists (file or branch), stop and ask the user to pick a different name

• Soft warning: if any existing plan title shares 3+ significant words with the proposed title, warn the user and ask to confirm this is intentionally separate work (only check Draft/Approved plans, not Delivered ones)

Smaller models: Skip the title similarity check. Enforce the hard gate (identical slug) only. Ask the user: "Could not check for similar plan titles. Please verify manually that this doesn't overlap with existing plans."

3. Create Branch

git fetch origin main git checkout -b idea/<slug> origin/main

4. Create Plan File

CREATE_DATE=$(date -u +%Y-%m-%d)

Write docs/plans/${CREATE_DATE}-<slug>.md using the template from skills/plot/templates/plan.md , substituting <title> and <slug> .

Ask the user what Type to use, presenting this reference:

Type Use when Examples

feature

New user-facing functionality API endpoint, UI component, CLI command

bug

Fixing a defect Crash fix, data corruption, incorrect output

docs

Documentation-only README updates, API docs, guides

infra

CI, build, tooling, release automation GitHub Actions, Dockerfile, linter config, deps

Always ask — don't infer from the title.

5. Create Active Symlink and Commit

mkdir -p docs/plans/active docs/plans/delivered ln -s ../${CREATE_DATE}-<slug>.md docs/plans/active/<slug>.md git add docs/plans/${CREATE_DATE}-<slug>.md docs/plans/active/<slug>.md git commit -m "plot: <title>" git push -u origin idea/<slug>

6. Create PR

Create a draft PR (plan is still being written/refined):

gh pr create
--draft
--title "Plan: <title>"
--body "$(cat <<'EOF'

Plan

See docs/plans/${CREATE_DATE}-<slug>.md on this branch.

Refine the plan, then mark ready for review with gh pr ready. Once reviewed, run /plot-approve <slug> to merge and start implementation.

Created with /plot-idea EOF )"

7. Add to Project Board

Read the ## Plot Config section from CLAUDE.md for the project board name. If configured:

gh pr edit <number> --add-project "<project board name>"

If no project board is configured, skip this step.

8. Summary

Print:

• Branch: idea/<slug>

• Plan file: docs/plans/<CREATE_DATE>-<slug>.md

• Active index: docs/plans/active/<slug>.md (symlink)

• PR URL (draft)

• Progress: [x] Draft > [ ] Approved > [ ] Delivered > [ ] Released

• Suggested next actions:

• Refine the plan (especially Branches and Design sections)

• When ready for review: gh pr ready <number>

• After review: /plot-approve <slug>

• Alternative: add to a sprint with /plot-sprint <sprint> then add [<slug>] as an item