planning-flow
/planning-flow
Układa plan zmiany w kodzie po zbadaniu bazy i pytaniach do użytkownika, zanim powstanie jakikolwiek kod.
- Autor
- patrickdappollonio ↗
- Repozytorium
- claude-plugins ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 20.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 10
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Układa plan zmiany w kodzie po zbadaniu bazy i pytaniach do użytkownika, zanim powstanie jakikolwiek kod.
Wyzwalacze z opisu
Oryginalny opis (EN)
Use when the user asks for a plan for a coding change — "plan this", "how would we build", "write me a plan for", "/planning-flow <ask>" — before any code is written, especially when the change needs research across a codebase, has open questions only the user can answer, or will be handed to an implementation step afterwards. Also use when a user complains that a previous plan read like a change-log of its own revisions.
Jak działa
- Overview
- Read the Companion Files First
- When to Use
- Two Authorities
- Where the Plan Lives
- The Process
- Closing
- Tickets
- Rationalizations — Observed, and Wrong
- Red Flags — Stop and Re-read the Step
Podgląd SKILL.md
---
name: planning-flow
description: Use when the user asks for a plan for a coding change — "plan this", "how would we build", "write me a plan for", "/planning-flow <ask>" — before any code is written, especially when the change needs research across a codebase, has open questions only the user can answer, or will be handed to an implementation step afterwards. Also use when a user complains that a previous plan read like a change-log of its own revisions.
---
# Planning Flow
## Overview
Turn a request into **one plan**: the current, complete answer to the user's ask, with the decisions that shaped it and the caveats that remain. The process behind it — a map of the codebase, parallel exploration, a zero-context review, rounds of questions, spikes, an adversarial review — exists to make the plan right; none of it belongs in the plan or in the message that delivers it.
**These rules bind everything below:**
1. **The plan never describes its own earlier versions.** Every revision rewrites the file in place so it reads as if written fresh today. The only record of the past is the decisions section, where you record a choice with its alternative and its reason. No "revisited", no "Edit:", no "after the review", no struck text, no revision headings, and no reviewer tally in chat.
2. **The reader has not seen the code.** You read hundreds of lines; the user read none. A function, file, or variable name is a label for a thing you must explain in plain words, never the explanation. Full rules in `communication.md`.
3. **Technical direction is yours, logged; functional and operational direction is the user's, asked.** The authority table below decides which is which, and a decision the user already made is never asked again.
4. **Facts are yours to find; decisions are the user's to make.** Find the facts yourself. Ask the user only what the codebase cannot answer. Ask every question in the one shape in `question-format.md`, and in chat ask one per message, each after the questions it depends on are answered. Never answer a question you put to the user. A change can be so simple that there are no questions; do not invent them.
5. **The plan is a document, and it plans the simplest thing that works.** The deliverable is markdown and nothing else — the plan file, and, outside plan mode, the shared codebase map step 0 keeps beside it: no prototype, mockup, scaffold, demo, or code is handed over as part of the plan. While planning, probes, prototypes, and scaffolds are encouraged as ways to check a fact (rule 8), under the permission lanes in `verification.md`, and are deleted before the plan is presented. Inside that file, use everything the viewer can render: Mermaid diagrams, diff and migration fences, API cards, file trees, question fences, a summary card. A picture of the design belongs in the plan; a working copy does not. The solution sits on the lowest rung of the ladder in `plan-template.md` that answers the ask: not needed → cut it; the codebase has it → reuse it; the standard library or platform has it → use it; an installed dependency has it → use it; otherwise the minimum that works. A higher rung is a decisions entry, rejected, with the reason. Never cut: validation at a trust boundary, data-loss handling, security, accessibility.
6. **Nothing an agent writes counts things that live elsewhere.** The plan, the codebase map, a decisions entry, a question, a message: none says how many there are ("the 24 handlers", "all seven tests", "three services"). The next one added makes the number wrong, and a stale number still reads as a fact. List the items, or state the rule that finds them; a reader who needs the number counts. A number stays only when it is itself the fact: a limit or threshold the code enforces, a quantity the work must use ("batches of 500"), a version, a size band, or a measurement with what it measured.
7. **Every subagent is one-shot; more work is a new subagent.** A mapper, explorer, reviewer, cold implementer, spike, or verifier gets one self-contained prompt, returns its result, and ends. It never waits for a reply, for the user, or for your next instruction, and you never resume, message, or continue it (`SendMessage` in Claude Code, or the equivalent elsewhere): a follow-up question, a re-run of the cold implementer check, and a second look at a finding each go to a **new** subagent with everything it needs in its prompt. A subagent left idle loses its prompt cache within minutes, so the next message re-reads its whole history at full price — often hundreds of thousands of tokens — and a reviewer that has already seen the earlier draft is no longer zero-context.
8. **An unknown a check can settle is settled now, or you ask to settle it now.** When you find an unknown whose answer would change the plan, run the check at once or ask the user for permission to run it, at that moment, not when the plan is presented. Never mention that something "could be tested" and move on. Which checks run unasked is decided by what they touch, never by their size (`verification.md`). **Run without asking:** reads inside the working directory (never a secret), installed dependency source, public docs, and read-only commands. **Run with a one-line note:** a throwaway probe in the scratch directory with no network and no installs, and existing tests you confirmed touch only this machine or a disposable local stack. **Ask first:** any network call past the machine, a browser MCP or any tool that drives the user's apps, a shared database or service, anything outside the working or scratch directory, installs, credentials, money, long runs, and prototypes bigger than a probe. When in doubt, ask. A request names each check, exactly what it reaches, where that target came from, and why the plan needs the answer.
9. **Long commands keep a heartbeat no more than three minutes apart.** A subagent's prompt cache expires about five minutes after its last model request, and while it waits on a command it makes no requests, so a silent wait past five minutes re-reads its whole history at full price. Any command that may run past three minutes (a full test suite, a build, an E2E run, a container start) starts in the background with its output and exit code going to a log, for example `( <command>; echo "EXIT=$?" ) > <log> 2>&1 &`. The subagent checks it with a foreground loop capped at three minutes, `for i in $(seq 18); do grep -q '^EXIT=' <log> && break; sleep 10; done; tail -n 3 <log>`, and repeats until the log shows `EXIT=`. A bare `sleep` may be refused by the tool; the loop is not. It never waits on a monitor or notification with no cap, and never ends its run while the command is still going. If the expected wait is longer than about 40 minutes, it skips the checks: one cold restart is cheaper. Do not act on a subagent until its final report arrives; a notice that it is still waiting on its own work is not a result.
## Read the Companion Files First
This skill ships in two layers. `SKILL.md` carries the rules and a summary of each step; the files beside it carry the full procedures:
- `codebase-map.md` — step 0: where the codebase map lives, how to tell fresh from stale, the mappers and what each covers (structure, features and flows, patterns and recipes, testing and the test inventory, rules and concerns, and services and access when the repository serves requests), the rules every mapper follows, the template, and how later steps use the map
- `plan-template.md` — the plan file skeleton, the ticket format, the decisions entry format, the size bands, and the timeless-prose rule with examples
- `communication.md` — how to write for a reader who has not seen the code: the identifier rule, Simplified Technical English (ASD-STE100), outcome-first messages
- `interviewing.md` — the design tree, the frontier, one question at a time, fog, out of scope, the rule never to answer your own question, and what every stop carries — including under a goal loop
- `question-format.md` — the one shape every question takes (numbered heading, the situation, the flow, the fix, the cost, your call), how to check the facts and the fix before asking, its heading level, where the questions live (all in the file, one per chat message), and how a `question` fence carries the answer in a visual plan
- `verification.md` — settling unknowns while planning: the three lanes (run, run with a note, ask first), how to tell what a test suite touches, the effort-to-reward rule, when to check, the permission request's shape and its untrusted-target rule, probes and prototypes, spikes, and check subagents
- `plan-review.md` — the zero-context reviewer, the cold implementer, and the adversarial review of a plan (installed skills or an on-the-spot panel) with its sizing rule
- `model-routing.md` — which tier explores, which tier reviews, the model names, and what to do when the harness cannot choose
- `companion-skills.md` — what `visual-plan`, `adversarial-review`, `adversarial-review-quick`, `adversarial-review-fast`, and `implement-plan` add when installed, and the install lines to give only when asked
**The first time you use this skill in a session, read every file in that list before doing anything else** — before mapping, before exploring, before drafting, before answering a question about the ask. The summaries here remind a reader who has already seen the full text; they are not a substitute for it. Re-read the named file at the step that names it. If a file is missing, say so and work from the summary — do not pretend the summary was the whole skill.
Every companion skill is optional. This skill works alone. When one is installed, use it; when it is not, use the distilled version here and never suggest installing anything unless the user asks.
## When to Use
- The user asks for a plan, a design, an approach, or "how would we do X" for a coding change, and no plan exists yet — or invokes `/planning-flow`.
**When NOT to use:** a plan already exists and the user wants it built — that is implementation; point at the `implement-plan` skill if installed, or the harness's own execution, and stop. Or the user asked a question, not for a plan: answer it.
## Two Authorities
| Yours (technical) — decide, then log it | The user's (functional / operational) — ask, never assume |
|---|---|
| Data structure, algorithm, file layout, naming, error type | What the user sees: output format, wording, new flags or syntax, defaults |
| Which existing pattern to follow; how to isolate a test | Whether a behavior the ask left open should exist at all |
| How to close a gap the review found, when the plan still does what the ask wants afterwards (making the asked-for behavior actually happen counts) | Anything that changes an API, a schema, a stored format, a cost, a deployment |
| Order of tickets, what is a spike | One pull request or several (see *Delivery shape*) |
| Keeping a detail the user specified when it seems awkward | Deviating from what the user asked for — even to "improve" it |
**The test:** if a reasonable user could say "I didn't want that", the decision is theirs. What decides it is behavior, not whether the choice is technical: a choice that changes nothing a user or a consumer (any person or system that uses the product's output) would notice is yours, technical or not, and a choice that changes what they notice is theirs. Check every decision you make against the code as it is now, never your memory of it. Trace the consequence of every technical choice before you make it. The choice belongs to the user if it changes output, ordering, timing, defaults, error behavior, or what is stored and where. It also belongs to the user if it changes how the thing is deployed, configured, monitored, or paid for. This holds even when the choice looks like an implementation detail. Log your decisions in the plan's decisions section with the alternative, the reason, and any drawback. Park theirs as questions.
**Never ask a question the user has already answered.** An instruction the user gives in chat is a decision: write it into the decisions section when they give it, quoting their words and naming what it was about, so a later reader cannot stretch it past that subject. Before asking anything, read the decisions section and every message the user sent. If their words settle the question, or lets you infer the answer with confidence, decide it yourself in the direction the user already chose, and log it as a decision that follows from theirs. Asking twice is the failure this rule prevents. A conditional instruction whose condition you checked and found true is settled. "All" covers what you found after the user said it. A new cost of their decision is a line in your message; it is never an alternative that undoes the decision.
## Where the Plan Lives
The plan is one markdown file, and the file is the single source of truth. Viewers (plan mode, a visual plan) show the file's content; they never hold content the file lacks. The file is also the only thing this skill writes, besides the codebase map in the same folder (step 0): a request for a plan is never a request for a working example, a page that shows the idea, or a starting scaffold, however small. Describe, and draw with every fence the `visual-plan` viewer renders — diagrams, diffs, migration and API cards, file trees, question fences — but do not build.
- **The session started in plan mode** (the harness told you writes are limited to its own plan file): the harness plan file *is* the plan. Write nothing else, not even the codebase map (`codebase-map.md` says how step 0 runs then); everything below still applies to its content.
- **Otherwise, inside a git repository:** write to `.plans/<task-name>.md` under the repo root. If `.plans/` already exists and holds files that are not plans from this skill, use `.planning-flow/` instead. Keep the folder out of the diff by appending its name to the repository's local exclude file, which is never committed and never touches the user's `.gitignore`:
```
git rev-parse --git-path info/exclude
```
prints the file to append to (create it if missing; skip the line if it is already there). If the user says they want the plan committed, remove the line and tell them.
- **Not a git repository:** write to the scratchpad or temp directory your harness gives you, and tell the user the path.
Name the file after the task in kebab-case, short and without filler words: "add rate limiting to the public API" becomes `add-api-rate-limiting.md`. Start fresh for every new ask; only revise an existing file when the user points you at it and it describes this change.
## The Process
Do every step in order. Read the named file at its step. Between steps, keep chat to one-line status notes; the plan is where the tokens go. **Every stop is complete on its own** (`interviewing.md`): it opens with `Step <n> of <m>; <k> questions open`, where `<m>` is the number of the last step below, carries the one question it asks in full — in the shape of `question-format.md`, the same text the file holds — and any command or file you need; never a pointer to an earlier message, never a second question. The file holds every open question; the chat asks them one at a time. **Under a goal loop** (the user said so, or the conversation holds `A session-scoped Stop hook is now active`, `Stop hook feedback:`, `Goal check-in:`, or a Codex `<objective>` block) every stop is the last message the user reads; a re-prompt with nothing changed gets it again, identical.
### 0. Map the codebase
Reply with one short sentence that acknowledges the request and says you are mapping the codebase first. Then read `codebase-map.md`, the file that defines the map, and `model-routing.md`. Choose the plan folder and add its exclude line now, as *Where the Plan Lives* says, because the map is written there before the plan is. The map describes the whole repository as it is today — stack and structure, modules, entry points, features, one end-to-end flow per kind of entry point with `path:line` at each step, and for a repository that serves requests, every route with its middleware, how callers sign in, and what each route lets them do, the patterns and conventions to copy with an example of each, recipes for the common extension points, how tests run and a test inventory of what each test file exercises, CI, the repository's rules, integrations, and concerns. It lives in `codebase-map.md` in the plan folder, stamped with the commit it was made from, and every plan in the repository reuses it. Check the stamp yourself, never ask: no map or a stamped commit that no longer exists means map everything; files changed since the stamp (`git diff --name-only <sha>` and untracked files) mean re-run only the mappers whose sections those files touch, or all of them when three or more are touched; nothing changed means reuse it as it is. In plan mode, outside a git repository, or in an empty repository, follow the exits in `codebase-map.md`. Mapping runs the mappers `codebase-map.md` lists on the cheaper tier in parallel, in one message, including the services-and-access mapper when the repository serves requests; you assemble the file and check one cited line per section against the code. Mappers never learn what is being planned, never read or quote a secret, and describe only what the code does now. A plan never points at the map: its facts are copied into *Technical context*, because the cold implementer does not get the map.
### 1. Capture the ask
Write the plan file's *The ask* section. **The ask is the task the plan is for — what is to be fixed, built, or changed — never the request for a plan.** "Can we make this into a plan?", "plan this", and the command that loaded this skill are how the user called the skill; none of them goes in the file. The section has these parts, in this order:
- **The task, in one sentence.** What is to be fixed, built, or changed, and for whom. Use the user's wording when they stated it. When the task took shape across the conversation and the user never stated it, state it yourself from the problem they raised or confirmed: this sentence is yours to write, and leaving it out to avoid a paraphrase leaves a section nobody can measure against. An approach you proposed and the user did not accept is not part of the task; it enters the draft as a decision or a question.
- **The user's words, verbatim, under it.** Every message of theirs that states the task, a constraint, or a non-goal, each as its own quote, in order, from wherever in the conversation it sits. Never reworded. When the message that called the skill also carries the task ("/planning-flow add rate limiting to the public API"), quote the task and drop the command.
Test the section before moving on: **a reader who never saw the conversation can tell from it what is to be built or fixed.** A section that would fit above any other plan unchanged holds the invocation, not the ask. If you cannot tell what "this" points at, ask in one plain line before exploring. The reviewer in step 5 and the final self-check both measure against this section.
### 2. Explore in parallel
Read `model-routing.md`, the file that says which model tier runs each role. Dispatch exploration subagents on the cheaper tier, in one message, each with the codebase map (or the sections that bear on its question) and one bounded question: where does the affected behavior live, what tests cover it, what documents describe it, what does the data look like, what do the existing patterns look like, what external dependencies are involved. These questions are always asked: for each file the change creates or modifies, the closest existing example to copy and the recipe that applies; and for each surface the change touches, which existing tests already exercise it or overlap with what the change must prove, so acceptance criteria extend them instead of adding new tests. Explorers start from the map and read the current code for the area; they do not map again. Each subagent returns facts with file paths as evidence. When an explorer's question needs a check from the two run lanes of `verification.md` (running a local test, a probe in the scratch directory), it runs it and reports the output; an unknown that needs an *ask first* check comes back to you, and you put the permission request on the question list now (rule 8). You keep the synthesis. When an explorer finds a line of the map wrong, fix that line in the map. Do not explore serially, and do not do the bulk reading yourself when a subagent can. A follow-up question goes to a new explorer with the earlier answer in its prompt, never to the one that already reported.
### 3. Draft the plan
Read `plan-template.md`, the file that defines the plan's shape. Write the full skeleton, in the template's order: the ask, summary, the problem, the solution, technical context, tickets, decisions, gotchas and caveats, out of scope, open questions with its "not yet specified" list. Write tickets in the format below. Write every decision you made while drafting into the decisions section as you make it. List what you do not know. A decision is an open question for the user. A fact goes through rule 8 as you write it down: read `verification.md`, then run the check or put a permission request on the question list now. A spike ticket holds only a check the user deferred or declined, or one this session cannot run.
### 4. Simplify against the ask — run it, never ask whether to
Before any reviewer sees the draft, read the ask once more and write, in one sentence, what must be true when the work is done and for whom — the goal, not the mechanism. Then walk the plan top-down with the ladder in `plan-template.md`, one question per part of the solution and per ticket: **if this part were removed, would the goal still be met?** If yes, cut it. If no, find the lowest rung that keeps it — the codebase already has it, the standard library or the platform has it, an installed dependency has it, a maintained library or a supported extension point has it, it is one line — and rewrite the part at that rung. A part that hand-writes any of a published format, protocol, or standard where a maintained library exists is rewritten to name the library; because a new dependency changes what the project needs at runtime, that one goes on the question list with the library as the recommendation and its facts read from the registry, as `plan-template.md` § *The ladder* describes. Every cut and every lowered rung is a decisions entry, yours, with the alternative and the reason. A simplification that would change what the user sees or gets is not yours: it goes on the question list with the simpler path as the recommendation. This step is neither offered nor skipped: it runs on every draft, and again on the finished plan in step 11. Cutting never reaches validation at a trust boundary, data-loss handling, security, or accessibility.
### 5. Zero-context review and cold implementer check
Read `plan-review.md`, the file that defines every review this skill runs. **No reviewer sees a draft whose shape hangs on a pending check** — a result that could add, remove, or resize a ticket. Wait for it, or for the user's answer to its permission request, unless they deferred it. Then dispatch two fresh subagents in one message, neither with conversation history, reassurance, or a list of what you already checked.
Tell both to ignore the plan folder: it holds the codebase map, which would let them trust what they should check.
- **The zero-context reviewer**, on the most capable tier your harness offers, with exactly these things and nothing else: the plan's *The ask* section as written (the task sentence and the user's quoted words), the plan file, and access to the codebase. Its charter: assume the plan fails the ask and prove it — gaps, wrong premises, missing cases, questions the user must answer, things the plan asserts about the code that are not true. It returns findings and candidate questions.
- **The cold implementer**, on a different model family from yours when the harness offers one (a Codex agent, for example) and on the cheaper tier otherwise, with the ask and the plan's *Technical context* and *Tickets* sections only, and no repository access at first. Its charter: restate the challenge, grade whether it could start implementing from this text alone, and list every exact string, format, path, convention, command, and location it would still have to go and find; then open the repository and report what the text got wrong. Every item on its list that would change what gets built is a gap in *Technical context*; fill each with the exact value and run the check again — a **new** cold implementer each time, given the rewritten sections — until the list holds nothing of that kind. An implementer still opens the file it edits; the surrounding text of an insertion point is not a gap.
The reviewer finds what the plan gets wrong; the implementer finds what the plan leaves out. A plan that passes only the first is correct and unimplementable.
### 6. Build the design tree, then filter it
Read `interviewing.md`, the file that defines how questions are found, filtered, and asked. There is **one** question list for the whole flow, whatever the source: your own notes, the zero-context reviewer, the adversarial review, spike results, a walk through your own plan for every "assume", "probably", and "for now". Arrange it as a design tree: each decision under the decision it depends on. Then remove from it, in order:
1. Anything the decisions section or the user's own messages already answer or imply (rule 3) — decide it in the user's direction and log it as following from theirs.
2. Anything the codebase or an experiment can answer — it is a fact, not a decision. Run it in one of the two run lanes of `verification.md`, or turn it into a permission request when it is *ask first*. Only the questions downstream of it wait.
3. Anything technical under the authority table — decide it, log it.
What remains is what only the user can answer. **If nothing remains, say so in one line and skip step 7.** Never pad the list.
### 7. Ask the frontier, one question at a time
Read `question-format.md`, the file that defines the one shape every question takes. Write **every** open question into the plan's *Open questions* section in that shape: `### Question <N> of <M> — <the claim>` (one heading level below the section), then **The situation.**, **The flow.** (three to five numbered steps to the consequence; one or two when that is the whole story, more than five only when absolutely needed, never past ten; `N/A` only when nobody would notice), **The fix.**, **Cost.**, then *Your call* — every part, in that order, its prose at most 200 words (15 more for each flow step past the fifth, on the rare flow that needs them). Before a question is written or asked, check that its facts hold now and that its fix works — the API, flag, version, or command it names exists as installed — and end the fix with `Not verified: <what>, because <why>.` for a part you cannot check from here. Only a direct accept, reject, or different direction closes a question; a vague reply or a question back gets the same *Your call* line again. Frontier first — every question whose prerequisites are settled, the ones that unblock the most others earliest; a question that waits on another sits below it and says so.
Then ask **in chat, one question per message**: the first frontier question, word for word from the file, under the position line, with the count of what else is open and the file's path. Never through the harness's question tool — its fields cannot hold a flow — and never two at once. Wait. Fold the answer in (step 8), recompute the frontier, renumber the open questions (answered ones still count, so `Question 1 of 5` is followed by `Question 2 of 5`), ask the next one in the next message; as many rounds as it takes, until nothing is open. When `visual-plan` serves the file, each question's **Your call** line is a `question` fence, so the user may answer there instead; chat still carries one at a time. **Never answer your own question**: no likely answer filled in, no silence taken as consent.
**Delivery shape is always on the frontier when the work is bigger than one small ticket:** one pull request for everything, or several. State the trade in one neutral line each — one PR is a single review and a single merge; several are smaller reviews and more coordination — and **give no recommendation**. Large tickets and large PRs are legitimate; writing code is cheap now and the user decides how to review it. Never nudge toward splitting. This question decides how the work is split, not when a pull request is opened. **Opening a PR is the user's call, made when they are ready**: no question, ticket, closing line, or `/goal` asks or plans to open one. Asked too early, it is one more thing they must answer instead of ignore. If they bring it up, answer it.
### 8. Rewrite the plan in place
After every round of answers, review findings, or spike results: rewrite the affected sections so the file reads as one plan written today. Record each user answer as a decision (theirs), each technical choice you made as a decision (yours, with drawback), and delete the answered question. A resolved spike disappears as a ticket: its answer goes into the decisions section and the tickets it affected. A ticket a review removed disappears; the reason lives in the decisions section. Re-read the changed sections against the timeless-prose rule in `plan-template.md` before moving on.
### 9. Present the plan
Read `companion-skills.md`, the file that says what each optional skill adds. Choose the viewer:
- **`visual-plan` skill installed:** use it to render and serve the file. Tell it, and yourself, that **the audience for this document is technical**: its rule to write for a non-developer does not apply, and its linter's warnings about code symbols in prose are expected and may stay. Every other part of it applies, including its own no-change-log rule.
- **No `visual-plan`, harness has a plan mode:** present through it with the file's content, unchanged. Enter plan mode only for the presentation.
- **Neither:** give the path and a summary in chat, in the shape under *Closing*.
The file stays the source of truth; a viewer's comments are folded into it.
### 10. Offer the deferred checks again
Checks are run or asked for when they come up (rule 8), so this step is a sweep. In the same message that presents the plan, list every check the user said "later" to, and every spike ticket this session could now close, each with what it reaches and what it would change, and ask whether to run them now. The user may decline again. Do not offer the adversarial review here: a review of a plan that still has open questions is paid for twice.
### 11. Fold in what came back, then ask the leftovers
A spike answer folds in as step 8 describes. Recompute the frontier and run step 7 until it is empty. When it is, walk step 4 once more over the whole plan: rounds of answers add parts, and a part added under pressure is the one most likely to sit a rung too high.
**Second opinion on your own decisions.** Before the plan counts as finished, dispatch one fresh, one-shot subagent, on a different model family from yours when the harness offers one (a Codex agent from Claude, `claude -p` from Codex) and on the cheaper tier otherwise. Give it the ask, every decision you made on the user's behalf since the last second opinion (each with what was chosen and the alternative), the plan file, and the repository. Do not argue for your choices or say which ones you are sure of. Its charter: for each decision, check it against the code as it is now and say whether it fits the ask, what caveat it carries, and whether it changes anything a user or a consumer (any person or system that uses the product's output) would notice. Its prompt ends with the single-task line. A decision it confirms stays. A caveat that changes nothing a user or consumer notices: adjust the decision by your own judgement and log it. A decision that changes such behavior: it was never yours, so it goes on the question list in the `question-format.md` shape. One subagent covers the whole batch; a later batch (after the adversarial review's fixes, for example) gets a new one.
The plan is finished when no question is open, no spike is pending, the cold implementer's list holds nothing that would change what gets built, the second walk cut nothing, and the second opinion found no decision that changes what a user or consumer would notice.
### 12. The one adversarial review — only when nothing is open
An adversarial review is the most expensive thing this skill can do, so it runs **once**, on the finished plan, and only when the user picks it. Size it with the table in `plan-review.md`, by **what the plan would change once built** — the code its tickets would touch and the subsystems — never by the plan file's own length, which diagrams and examples inflate. The lines are the code review's: fast for about 500 lines or fewer in one subsystem, quick for 2000 lines or fewer in one subsystem, full above that, and full whenever the plan touches the database schema, sign-in and permissions, work that runs at the same time, or an outside service. Offer it in plain text — **fast, quick, full, or none** — with the estimate in one line, your recommendation, and the cost of each in plain words (fast is one agent; quick is the fitting reviewers plus two checkers; full is roughly twice quick). Run exactly what they chose, once: the installed `adversarial-review-fast`, `adversarial-review-quick`, or `adversarial-review` skill when present, given the plan file as the change under review and **the plan's *The ask* section, as written, as the standard the plan must meet**; the on-the-spot panel, or its one-reviewer version for fast, from `plan-review.md` when the chosen one is not installed. An installed skill's last step, putting every finding to the user, does not run here: tell it that this skill decides the findings, and take the report and the validated fixes back.
The plan exists to reach the ask, so a finding inside the ask is fixed, not asked. **Rewrite the plan without asking, and log it as your decision with the reason and any drawback,** for every finding whose fix is technical or corrects a mistake and leaves the plan doing what the ask wants: a correction that makes the asked-for behavior actually happen (a warning the ask wants in Slack that the plan's rule would never send) counts, because making the asked-for behavior happen is not a change in behavior. **Add it to the one question list,** with the reviewer's suggestion as the recommendation, and run it through the same filter and frontier as every other question (steps 6 and 7), only when the fix changes how the product behaves for its users or consumers beyond the ask or a decision the user made — the business process, what users see or get, an operational policy such as a threshold or a schedule — or is large (a new dependency, a schema or stored format, a public API), or reaches outside the ask. A `design_is_wrong` finding takes the same test. Never ask whether the plan should do what the ask already wants. Rewrite in place. Never write "the review found" anywhere in the plan.
When the fixes are in, ask before any second review: say what was found and what changed, and recommend a second run only when a finding changed the solution or a ticket's scope — usually fast, sized by what changed; otherwise recommend none. **No second review without a yes.** A no ends it.
### 13. Close
When the last question is answered and nothing else is open, send the closing below. **Asking for approval is not a question.** It has no trade-off for the user to weigh, so it never gets the question template: no `Question <N> of <M>` heading, no situation, flow, fix, cost, or *Your call*, and it never counts as an open question. The closing ends with one plain line asking whether to implement, and the user's yes to that line is the approval.
## Closing
The closing message is the plan, not its history. Exactly this shape, short:
- **Where the plan is** — the path (and the URL when served).
- **What it does** — two or three plain sentences: the problem, and how the plan solves it.
- **Does it cover the ask** — one line, measured against *The ask* section: the task and every quoted constraint.
- **Gotchas and caveats** — the ones that survived, each a line.
- **Decisions you should know about** — the ones you made on the user's behalf that they might want to reverse, each in one line: what was decided, why, and its caveat (a review finding you fixed on your own is one line here, saying what the plan now does, never who found it), and every manual step only they can do, written out in full, never as a pointer back.
Never: how many revisions there were, what reviewers said, what changed since the draft.
Then ask, **in plain text in the same message, never through a question tool**, whether they want to start implementing: one line, with no template around it. Name `implement-plan` as the recommended next step when it is installed, otherwise say the file is ready for whichever implementation step they prefer. Plain text lets them answer with any skill or command they have.
Under that line, give a one-line `/goal` the user can paste to run the build hands-free, with the plan's real path filled in:
```text
/goal Implement .plans/<file>.md with implement-plan; done when every ticket's acceptance criteria pass.
```
Drop `with implement-plan` when it is not installed. Keep the goal to one line of about 20 words. That is a target for simplicity, not a budget: whatever length limit the harness sets, never write toward it. The plan file already holds everything else, so the goal names the file and the finish line and nothing more: never tickets, constraints, test names, the plan's summary, or how to commit. Commands, field names, request shapes, and status codes are already in the plan, and repeating them in the goal makes it too long and lets it drift from the plan.
**The goal never sets a commit count.** "As one local commit" forces a large, multi-ticket build into one commit that cannot be partly undone. Commits are free-form, and the user can squash them later. Pushing is different: nothing is pushed unless the user allows it, so the goal does not need to say so. The implementer may still recommend a push when a backup matters, such as before a risky step or to recover from one, and waits for a yes.
Wrong, because it restates the plan:
```text
/goal Implement .plans/csv-export.md as one local commit: add an --export=csv flag to the report command (quote every field, UTF-8 with BOM, exit 2 on a write error) plus a per-user export_dir setting, passing go vet and go test ./...; no push.
```
Wrong, because it fixes the commit count:
```text
/goal Implement .plans/csv-export.md until every acceptance criterion passes and CI checks are green, as one local commit, no push.
```
The end of a closing, right:
```markdown
Ready to implement? I recommend `implement-plan`, which picks up the plan file.
To run it hands-free: `/goal Implement .plans/csv-export.md with implement-plan; done when every ticket's acceptance criteria pass.`
```
## Tickets
Every unit of work is a ticket in **exactly** this format (full detail and an example in `plan-template.md`):
```markdown
## <Title>
**What.** …
**Why.** …
### Acceptance Criteria
* … — extends `<test file>` `<TestName>`
* … — new test: <reason>
**Depends on.** <other ticket titles, or "nothing">
**Size.** <XS | S | M | L | XL | XXL>
```
- **Title** — a plain imperative phrase. Spikes start with `Spike:`. **No ticket numbers, codes, or identifiers** — tickets are referenced by title. A quantity that is part of the work ("batches of 500") is fine; "#4", "PF-12", or "Ticket 3" is not. A numbered ticket ends up in the code as a `// see ticket 4` or `// PF-12: …` comment, which explains a past decision instead of the line under it. A title never ends up in a code comment.
- **What** — may be technical, and may span paragraphs. Every file, function, or symbol it names is explained in the same sentence in plain words; a reader who has never opened the repository must follow it. Prefer "the code that decides whether a supplier is switched on" to a bare name.
- **Why** — Simplified Technical English (ASD-STE100): short active-voice sentences, one idea each, common words, no unexplained jargon. What is wrong today, what is true when this ticket is done, and who benefits.
- **Acceptance criteria** — observable checks a reviewer can run, each ending with the test that proves it: `— extends <file> <TestName>` for an existing test on that surface, or `— new test: <reason>` only when no existing test on that surface performs 60% or more of the new test's setup and action steps. The research pass finds these tests and names them in the plan; the implementer adds the case to the named test and does not run its own count for that criterion. For a spike, the criteria are the questions it must answer.
- **Depends on** — titles only.
- **Size** — a guess at lines of code touched, never time. Bands, in lines: XS under 200, S 200 to 750, M 750 to 1500, L 1500 to 4500, XL 4500 to 6000, XXL over 6000. Every band is legitimate; a large ticket is not a defect and is not split unless the user asks.
## Rationalizations — Observed, and Wrong
| Excuse | Reality |
|---|---|
| "I already know this repository from earlier in the session, the map can wait" | The map is checked by its stamp, not by memory. A fresh map costs one `git diff`; a missing one is built before anything else. |
| "The change is small, mapping the whole repository is overkill" | The map is built once per repository and reused by every plan after it. Step 0 on a fresh map is a stamp check. |
| "The map has the convention; *Technical context* can point to it" | The cold implementer never gets the map. Copy the value into the plan. |
| "No test covers exactly this, so the criterion gets a new test" | The test inventory lists the tests that exercise the surface, and an explorer confirms them against the code. A test that does most of the setup and actions is extended, not copied. |
| "The user's last message is the ask, and the rule says their literal words" | The message that called the skill asks for a plan; the ask is what the plan is for. Write the task in one sentence, then quote the messages that state it and its constraints. |
| "The task took shape in my messages, so stating it would be my paraphrase" | The task sentence is yours to write when the user never wrote one; build it from the problem they raised or confirmed. Your unaccepted proposals stay out of it. |
| "I'll add an *Update* section so the user can see what changed" | The user asked for the plan, not its diff. Rewrite the section. The decisions log is the only memory. |
| "Keeping the old paragraph with a note is faster" | Faster to write, unreadable to read. In place, always. |
| "The reviewer found seven issues; the user should know" | They should know the plan is sound. Fold in the fixes, log the decisions, present the plan. |
| "The reader is technical, so function names are fine" | Technical is not the same as having read the code. Name it and explain it in the same sentence. |
| "I'll number the tickets so dependencies are easier to write" | Titles do the same job and never end up in a code comment. |
| "Three questions in one message is faster than three messages" | Three questions in one message is a wall the user reads three times. The file holds all of them; the chat asks one, waits, asks the next. |
| "I'll ask the default and the table in the same message to save a trip" | The default depends on the table. A question whose prerequisite is open waits for the answer. |
| "The user is here, a one-line question is quicker" or "the flow is obvious, N/A" | The shape is what makes the question answerable away from the code: heading, situation, flow, fix, cost, your call, every time. `N/A` is for a decision nobody would notice — if someone would, walk them to it in numbered steps. |
| "The harness has a question tool, I'll use it for this one" | Its fields hold one line per option and no flow. The question goes in the message as markdown, and the user answers in their own words. |
| "The user is away, so I'll take my recommendation as their answer" | A question put to the user is answered by the user. The question stays open in the plan until they answer it. |
| "I asked that two messages ago; a pointer is enough" or "the goal check keeps rejecting, one line will do" | The user's screen holds the last message. Every stop carries its one question in full; answer a re-prompt with the same full message, word for word. |
| "The whole question fits in the fence description" | The description renders as one inline line; a numbered flow becomes a run-on sentence. Prose above the fence, only the *Your call* line inside it. |
| "I'll write the bold *Your call* line; they can answer in chat anyway" | When `visual-plan` is serving the file, the file's *Your call* is a `question` fence from the first draft; chat gets the bold line with the alternatives as a list. |
| "I can't phrase it sharply yet, so I'll skip it" | Write the unclear area under *Not yet specified*. Turn it into a real question once the questions ahead of it are answered. |
| "The user answered something close to this earlier" | Close enough is decided. Decide it in their direction and log it as following from their answer. |
| "This decision is technical, so it's mine" | Only while its effect stays invisible. Trace the consequence first. |
| "Several PRs is best practice, I'll recommend it" | Delivery shape is the user's, with no recommendation. State both trades neutrally. |
| "I'll ask whether to open a PR when the build is done" | The user asks for a PR when they want one. An early offer is a question they have to answer for nothing. |
| "This ticket is 5,000 lines, I should split it" | XXL is a band, not an error. Split only when the user asks. |
| "I'll leave the resolved spike ticket so the work is visible" | The answer is the work. It lives in decisions and in the tickets it changed. |
| "The change is small, so I'll skip the zero-context reviewer" | Small changes get the same one reviewer; it is one subagent. Nothing gets no review. |
| "The plan is solid, I'll run the adversarial review now and ask the leftovers after" | A review of a plan with open questions reviews a plan that will change. It runs once, when nothing is open, and only when the user picks it. |
| "The fast or quick review is cheap enough to run without asking" | No panel runs without the user choosing it. Offer fast, quick, full, or none, with the cost of each, and take no. |
| "The findings changed the plan, so it needs a second review" | Ask. Recommend a second run only when the solution or a ticket's scope changed; a no ends it. |
| "The technical context names the files; the implementer can read them" | Then the implementer explores, and the plan did not do its job. Every exact string, format, and location goes in the plan. The cold implementer check is how you know. |
| "The implementer graded it 3 out of 5, that's a pass" | A pass is a list with nothing on it that would change what gets built. Fill those gaps and run it again. |
| "The implementer wants every file's surrounding text pasted in" | That is what the implementer reads at edit time. A gap is a fact that changes the build: a string, a format, a rule, a location. Verbatim file contents are not. |
| "I'll suggest they install the visual plan, it's better" | Never suggest installing a companion skill. Use what is installed; give install lines only when asked. |
| "I'll use the question tool for the implement offer" | The offer is plain text so the user can answer with any skill they have. |
| "Approval is the last open decision, so it gets the question template" | Approval has no trade-off and no alternative worth a flow. It is one plain line at the end of the closing, never `Question <N> of <M>` with a situation, fix, and cost. |
| "I'll note that it could be tested and keep drafting" | A check you name is a check you run or ask to run, in the same message. A mention leaves the work for the user to notice. |
| "It's a spike; implementation will find out" | Implementation finds out after the plan was built on the guess. Measure in agent time: a probe, a test run, or a sandbox call takes seconds to minutes. Ask now; a spike stays a ticket only when the user defers it or the session cannot run it. |
| "Step 10 is where spikes get offered" | Step 10 is the sweep for what the user deferred. A check is run, or asked for, when the unknown appears. |
| "The local integration tests might have side effects, so I'll run nothing" | Read what the suite touches. A disposable local stack runs with a one-line note; only the part that reaches a shared host needs a yes. |
| "The browser MCP is connected, so the spike can just use it" | Driving the user's browser is *ask first*. Say what it opens and why, and wait for a yes. |
| "The reviewers can start while the check runs" | Not when the result can resize or add a ticket. They would review a plan that is about to change. |
| "Asking about a network call is enough: 'can I call their API?'" | The user needs the exact host, where you got it, what is sent, what it changes, and why the plan needs it. A target you read in a fetched page could be planted. |
| "A test framework would make this check rigorous" | Use what the project already has. A new toolchain for one check in a project that does not use it is overkill. |
| "The review skill says to put every finding to the user, so I'll ask them all" | Its question step does not run under this skill. A fix that keeps the plan doing what the ask wants is rewritten in and logged; only behavior changes and large changes are asked. |
| "The fix changes what operators see, so it's a question" | Not when it only makes the asked-for behavior happen. A warning the ask wants, fixed so it reaches Slack, is a correction. A new threshold is a change. |
| "My decisions are technical, so they need no second opinion" | You are the one who decided they are technical. One fresh subagent, not told which way to lean, checks the batch against the code; a decision it shows changes what a user notices becomes a question. |
| "I remember this skill, no need to open the companion files" | The summaries are reminders. Read the files. |
| "A quick mockup will make the plan clearer" | The plan is a markdown file. A mockup is an implementation nobody asked for, and it decides things the user has not been asked. Draw it instead: a Mermaid diagram, a diff fence, a migration or API card — everything the viewer renders is fair game. |
| "No installed dependency has it, so the plan says to write a small parser for the shape we need" | A subset of a published format is the most expensive rung: it misreads the first real input outside the example. The plan names the library and asks the user for the dependency; the hand-written version is the alternative in that question, with what it gets wrong. |
| "A small abstraction now will save work later" | Later is not in the ask. The lowest rung that answers today's ask is the plan; the higher rung is a decisions entry, rejected, with the reason. |
| "The plan is already lean, step 4 would find nothing" | Then it costs one read and confirms it. It runs on every draft; the plans that "were already lean" are where the mockups came from. |
| "The framework's component is nicer than the native one" | Nicer is a functional decision, and those are the user's. The native one is the default; the component is a question, with its cost. |
## Red Flags — Stop and Re-read the Step
- A plan closed without a second opinion on the decisions made on the user's behalf, or a second-opinion prompt that argues for the choices
- A review finding whose fix makes the asked-for behavior happen, asked instead of rewritten in; a review skill's apply / defer / dismiss questions asked during planning
- A draft written before step 0 ran this session, or a map reused without checking its stamp against the current commit
- A *Technical context* that says "see the codebase map" instead of the values; the map handed to the zero-context reviewer or the cold implementer
- A secret value, or a description of the change being planned, in the codebase map
- A ticket that adds or changes a route without stating who may call it, how they sign in, and where that is enforced
- An acceptance criterion with a new test when the test inventory lists a test on that surface the explorer never checked
- Any heading or sentence in the plan containing a word from the delete table in `plan-template.md`: "revisited", "updated", "revised", "corrected", "previously", "as clarified", "as discussed", "after the review", "the reviewer noted", "Edit:", "Update:"
- *The ask* holding "can we make this into a plan", "plan this", or the skill's command; no task sentence above the quotes; or a constraint the user stated that is not quoted
- A struck-through line, a "for context" section, or a superseded paragraph kept beside its replacement
- A ticket with a number, code, or identifier in its title
- A sentence in *What* or *Why* that dies when its identifier is deleted
- A question on the list that the decisions section or the user's own earlier words already answer; a *Your call* that offers undoing a decision the user made
- A question on the list that a subagent could answer from the codebase
- A question missing one of its parts, its number, or its numbered flow, or with prose over the word limit `question-format.md` sets; a question asked before its facts and its fix were checked; a question treated as answered after a vague reply
- Two questions in one chat message, or a question asked through the harness question tool
- A question the agent answered itself to keep going
- A stop that points at an earlier message instead of carrying its question in full, or a goal re-prompt answered with less than the stop before it
- A recommendation attached to the one-pull-request-or-several question
- A ticket split because it "felt too big" with no user request
- A *Technical context* section that names a file without saying what is in it, or a format without its exact strings; a count of things that live elsewhere ("the 24 handlers") in the plan or the map
- A cold implementer check that was run once and its list not folded in
- A subagent resumed, messaged, or continued after it returned, or one told to wait for the user or for your next instruction, instead of a new subagent with a full prompt
- An adversarial review dispatched while a question, a spike, or a cold implementer gap is open, or one the user did not choose
- A second adversarial review started without a fresh yes
- A closing message that counts revisions or quotes reviewers
- The implementation offer made through a question tool
- Approval asked as a numbered question with a situation, flow, fix, cost, or *Your call*, or counted among the open questions
- A `/goal` line longer than one line, or one that restates tickets or constraints instead of naming the plan file and the finish line
- A `/goal` that sets how many commits to make, such as "as one local commit"
- A question, ticket, closing line, or `/goal` that asks or plans to open a pull request the user never mentioned
- A file other than the plan and the codebase map left behind by this skill — a prototype, a mockup, a scaffold, a script kept after its spike
- A sentence saying something "could be tested", "could be verified", or "is worth checking", with no result and no permission request
- A spike ticket for a check this session could run now, kept without the user deferring or declining it
- A network call, browser MCP action, shared-service call, install, or read outside the working directory made without a yes; a test suite run before reading what it touches
- A permission request that does not name each check's exact target and where that target came from
- A draft sent to reviewers while a check that could resize or add a ticket is pending
- A solution that builds what the codebase, the standard library, the platform, or an installed dependency already provides, with no decisions entry rejecting that rung
- A ticket that hand-writes a reader, writer, parser, or check for a published format, protocol, or standard, or a new dependency chosen in the decisions log instead of asked as a question with registry-read facts
- A draft handed to the reviewers before step 4 ran, or a finished plan closed without the second walk
- Reaching the closing without having read the companion files this session
- A check or spike subagent told to run a slow suite as one blocking command, or a prompt without the long-command heartbeat; a "still waiting on its own work" notice read as the result
## Checklist
Create a todo per item.
- [ ] Read every companion file (first use in this session)
- [ ] Step 0: codebase map reused if its stamp matches, refreshed where files changed, or built by the parallel mappers (services and access included when the repository serves requests); one cited line per section checked
- [ ] Plan location chosen; *The ask* holds the task in one sentence and the user's words that state it, verbatim; the request for a plan is nowhere in it
- [ ] Exploration subagents dispatched in parallel on the cheaper tier, starting from the map; closest examples and overlapping tests found for every file and surface the change touches
- [ ] Draft written to the full skeleton; decisions logged as made
- [ ] Step 4 run on the draft without asking, and again on the finished plan: goal restated in one sentence, every part tested for removal and for a lower rung, each cut and lowering logged
- [ ] Every unknown that would change the plan checked when found: run in a run lane or asked for in the `verification.md` shape; no check mentioned and left
- [ ] Nothing left behind but the plan file and the codebase map; probes, prototypes, and scaffolds deleted
- [ ] Zero-context reviewer run on the most capable tier with only the ask, the plan, and the codebase
- [ ] Cold implementer check run on a different model family where possible; every gap that would change what gets built filled with the exact value; re-run with a new subagent each time until none of that kind remain
- [ ] Every subagent one-shot: each follow-up, re-run, and second look went to a new subagent with a full prompt; none resumed or left waiting
- [ ] Every run-lane, spike, and cold-implementer prompt carries the long-command heartbeat; no subagent blocked on a slow command past three minutes, and no result used before the final report
- [ ] One question list from every source, arranged as a design tree, then filtered: decided, answerable by code, technical
- [ ] Every open question written into the file in the `question-format.md` shape — numbered heading, situation, flow, fix, cost, your call — each with its facts and fix checked before it was asked, and asked in chat one per message until a direct answer closes it and nothing is open; delivery shape included without a recommendation; no question answered by the agent; every stop opens with its position line and carries its one question in full
- [ ] Plan rewritten in place after every round; spikes and dropped tickets folded into decisions
- [ ] Presented through `visual-plan` (technical audience stated), plan mode, or chat
- [ ] Deferred checks offe
[…] pełny plik w paczce .zip
Pliki w paczce (10)
- SKILL.md 60 KB
- codebase-map.md 13 KB
- communication.md 7 KB
- companion-skills.md 5 KB
- interviewing.md 12 KB
- model-routing.md 3 KB
- plan-review.md 16 KB
- plan-template.md 16 KB
- question-format.md 18 KB
- verification.md 10 KB
Wersje
W bazie nie ma innych skilli o nazwie planning-flow.
Migawka bazy z 13.11.2026 · wersja paczki f1eaf22992e5 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100write-plan
Pomaga napisać plan implementacji zmiany, która ma już zamiar i specyfikację, zanim powstanie jakikolwiek kod. - 90sp-planning
Układa konkretny plan wdrożenia uzgodnionej zmiany, zanim napisany zostanie kod. - 100implementation-planning
Przygotowuje kompletny plan zmiany zachowania w istniejącym kodzie, oparty na aktualnym stanie bazy, zanim rozpocznie się implementacja. - 95write-implementation-plan
Przygotowuje plan wdrożenia po zbadaniu kodu: listę plików do zmiany, otwarte pytania i plan weryfikacji. - 100strategic-planning
Rozbija złożoną pracę programistyczną na zadania, zanim powstanie jakikolwiek kod produkcyjny. - 100planning-flow-quick
Tworzy krótki plan drobnej zmiany w kodzie, zgodny ze wzorcami repozytorium i z nazwanymi testami, bez pełnej mapy kodu i wielu przeglądów.