The /plan-with-me Skill

What it does

plan-with-me turns a fuzzy request into a written plan you actually agreed to — not a document the agent invented in one pass.

A plan generated from a one-line prompt relocates the guesswork: every unstated requirement becomes a confident sentence nobody signed off on. This skill replaces that with a conversation that converges. Two rules do most of the work:

One question per turn, and every question worth your attention.

Every unknown is resolved by evidence or handed back to you — never filled with an assumption.

The only deliverable is one Markdown plan file. No scaffolds, no “helpful” stubs, no commits. Implementation waits for an explicit go-ahead in a later turn.

When to reach for it

Invoke it when the work is too large, vague, or contested to start coding:

• A one-line feature request that hides decisions nobody has made yet
• Several designs are defensible and the choice changes the shape of the work
• A refactor, migration, or integration where sequencing and blast radius matter
• You explicitly want a plan, design doc, or RFC before building
• You started implementing and realised you don’t know what “done” means

Reach for something else when:

Situation	Better skill
The change is obvious once you’ve read the code	Just implement it
You’re diagnosing a bug with an unknown cause	debug-flow / find the root cause first
You need researched, cited answers	finder
You’re choosing production telemetry	instrumenting-for-observability
Nobody is there to answer questions	Don’t use this — unattended runs force assumptions

Prerequisites

You need an interactive session, read access to the codebase, and permission to write one Markdown file. The agent uses the host’s structured question tool when one exists (AskUserQuestion, AskQuestion, and similar) and falls back to prose. Web search helps close unknowns that aren’t in the repo.

How it works

1. Ground first — Read a bounded set of files. Restate where the change lands, prior art, and constraints before asking anything.
2. Fix intent — One goal sentence and a short “done when” list, confirmed by you.
3. One question per turn — Each question carries context from the code, 2–4 concrete options, a recommendation, and what changes in the plan depending on the answer. Facts get looked up; decisions get asked.
4. Resolve unknowns — Evidence or your answer — never a silent assumption.
5. Keep state visible — Running decisions stay in view so the plan doesn’t drift.
6. Stop when intent is met — From either side: you call it done, or the completion test passes.
7. Write the file — One plan at a confirmed path. Writing the file ends the skill.

What you get

A single Markdown plan with sections such as Goal, Done when, Context, Decisions, Considered and rejected, Plan steps, Verification, Out of scope, Open questions, and Risks.

Deep templates and the full question protocol live in the source skill.

Common questions

Can it plan and then immediately build?
No. Even if you asked for both, writing the plan ends this skill. Momentum is not consent — ask again after you’ve read the plan.

Why won’t it batch questions?
A batch of eight questions gets one easy answer; the rest get filled in by the agent. That’s how assumptions sneak into a document that looks collaborative.

What if the code already answers the question?
Facts are looked up, not asked. Precedent in the code is offered as the recommended option when the choice is still yours.

It’s working if

• The first thing you see is a short grounding restatement with file paths, not a questionnaire
• Questions arrive one at a time, each with options and a recommendation
• The plan’s claims trace to a file, a source, or something you said
• No repository files change except the one plan document
• Implementation doesn’t start until you explicitly say so after the plan exists

Where it fits

plan-with-me sits at the front of a careful build loop: agree the plan → implement → review. When a session ends mid-work, hand state to the next agent with handing-off-work. When a decision is blocked on external knowledge, close that gap with finder and return here.