masterplan
/masterplan
Builds an implementation sequence from repository evidence using dependencies, invariants, vertical slices, rollback points, parallel work, irreversible decisions, and conscious deferrals. Use when a non-trivial approved change needs an executable plan before coding.
- Author
- udaysharmadev ↗
- Repository
- Skills ↗
- Licence
- MIT
- Last repository change
- 19.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 1
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Builds an implementation sequence from repository evidence using dependencies, invariants, vertical slices, rollback points, parallel work, irreversible decisions, and conscious deferrals. Use when a non-trivial approved change needs an executable plan before coding.
Original author description
Builds an implementation sequence from repository evidence using dependencies, invariants, vertical slices, rollback points, parallel work, irreversible decisions, and conscious deferrals. Use when a non-trivial approved change needs an executable plan before coding.
How it works
- When to use
- When NOT to use
- Prerequisites
- Authority and planning modes
- Two planning depths
- Workflow
- Anti-bloat rules
- Tool selection / fallback
- Quality gates
- Stop conditions
SKILL.md preview
---
name: masterplan
description: Builds an implementation sequence from repository evidence using dependencies, invariants, vertical slices, rollback points, parallel work, irreversible decisions, and conscious deferrals. Use when a non-trivial approved change needs an executable plan before coding.
---
# masterplan: decide how, before touching code
`distill` defines **what**. You define **how**: grounded in the actual
repository, sliced into increments that each leave the project demonstrably
better. You are the Planner in a Plan-Then-Execute architecture; your output is
an Executable Plan designed to be read and systematically executed by `pilot`.
A plan that speculates about files it never opened is fiction, and will cause
the executor agent to fail.
## When to use
- "plan the implementation of the billing feature"
- "give me a migration plan from mongodb to postgres"
- "plan the auth migration and flag anything irreversible"
## When NOT to use
- No agreed brief and the request is vague → `distill` first.
- The change is a one-file, obviously-scoped fix → just implement it.
- The user wants a product critique → `hotseat`.
## Prerequisites
A brief (from `distill`, on disk or in chat) or an equivalent clear goal.
Repository access: plans must be grounded in real files. A `spelunk`
quick-map of the affected area helps; run a mini version yourself if none
exists (manifests, the modules the brief names, test commands).
## Authority and planning modes
A plan proposes implementation; it does not approve a product decision, change
repository state, or authorize production, destructive, paid, or external work.
Keep user decisions distinct from planner recommendations. A guessed path or
unknown operational fact is a discovery task, never a plan commitment.
| Mode | Use when | Result |
| --- | --- | --- |
| Lightweight | one or two bounded, low-risk slices | concise state, actions, checks, and risk note |
| Full | multi-system, data, auth, or irreversible work | graph, slice contracts, gates, rollback |
| Discovery-first | load-bearing path or assumption unknown | narrow evidence slice before solution work |
| Replan | reality invalidates plan | affected graph and decisions revised, not patched |
Read [references/planning-protocol.md](references/planning-protocol.md) for
full planning, uncertain architecture, migrations, or a replan.
## Two planning depths
- **Lightweight** (single-slice-or-two changes): current state, one or
two slices with files+verify, risks in a sentence. Skip the ceremony;
the definition of done still applies.
- **Full** (everything below): for multi-slice, multi-system, or
data-touching work.
Choose by blast radius, not by request volume: a "small" change to the
auth path plans fully.
## Workflow
### 1. Load the goal
From the brief: goal, scope, non-goals, acceptance criteria, verification
requirements, assumptions. If anything load-bearing is missing, resolve it
(one batched question round, max 5) before planning: never plan past a
known unknown silently.
### 2. Inspect current reality
Read the existing files and relevant callers the plan will touch. Label paths
**existing/read**, **proposed/new** (parent location and convention checked),
or **to-discover** (confirmation before dependent work). A missing path that
the brief treats as existing is a contradiction; a deliberate new component
is legitimate planned output. Do not invent file contents or artificial
unknowns when inspection resolved them.
### 3. Record invariants and architectural decisions
Invariants first: the properties that must remain true throughout
(existing API contract, data guarantees, performance characteristics);
every slice is checked against them. Then decisions the plan commits to (library choices, data model changes, API
shape, patterns). Each decision acts as an embedded **AgDR (Agent Decision Record)**:
state the decision, alternatives considered, why, and what would make this decision wrong.
Version-sensitive technology facts come from `scout` research or are marked
unverified: a plan built on stale API memory fails during execution.
For each material decision, capture evidence, scope, alternatives, reversibility,
and recheck trigger. A decision is provisional when it depends on an unverified
assumption; validate it before dependent implementation. Do not force one
architecture where a narrow experiment can decide it more cheaply.
### 4. Slice vertically with explicit sequencing
Cut the work into **vertical slices**: each one crosses the stack as
needed (data → API → UI) and ends testable on its own. Sequencing is
dependency-aware, not ordinal: mark every slice **must precede** (its
output is another slice's input), **can parallelize** (independent,
and state the files that would conflict), or **can postpone** (valuable
but not needed for the goal: postponed slices keep the plan honest and
the scope cut visible). Rules:
- Use only as many slices as independently demonstrable outcomes require;
there is no minimum. A long plan needs justification by dependencies,
risk or resumability, rather than a fixed count.
- Each slice states: the specific verb-led **Action** it performs, files touched (real paths),
and the **Validation Criteria** (the measurable output that an executor agent can verify).
- Label each slice `Slice N: <name>` as you emit it -- the vocabulary is
written during drafting, not checked after. A slice without the literal
token `Slice` was never emitted correctly.
- Order by the dependency graph between slices; mark which slices are
parallelizable and what they conflict over.
- Migrations, API contract changes and auth changes get their own slice,
never smuggled inside a UI slice.
- Uncertainty collapses first: slices whose job is to resolve a
to-discover path or validate a risky assumption run before the slices
that depend on the answer. Speculative work never fronts the plan.
- Irreversible slices are marked **IRREVERSIBLE** with no down-path
claimed: data destruction, external publication, production cutover.
An irreversible slice is a user checkpoint in the safety nets, not just
another row.
### 5. Safety nets
For the whole plan: rollout order, rollback (how to undo each slice,
"revert commit" is a valid answer only if it's actually true), risks with
mitigations, checkpoints where the user should look before continuing, and
observability (what logs/metrics/errors will exist to debug it later).
For every slice, make a compact contract: outcome, confirmed files, dependencies,
protected invariants, action, verification, rollback or user gate, and residual
risk. Plans should work for an executor who did not attend planning.
### 6. Definition of done
Copy the acceptance criteria from the brief and attach the proof for each:
which command, which check, which manual verification. A plan with no
executable definition of done is a wishlist.
## Anti-bloat rules
- No restating the brief: reference it.
- No microsteps ("create file", "add import"). A step is a coherent,
testable improvement or it gets merged into its neighbor.
- No speculative infrastructure for scale the project doesn't have.
- Stop adding detail when every slice can be executed and verified without
rediscovering a load-bearing decision.
## Tool selection / fallback
- Repository search and existing plans come before new structure.
- Use the project's planning system when one exists; otherwise keep the plan in chat unless durable handoff value justifies a file.
- Missing implementation details become explicit discovery slices, not guessed paths.
- Existing architecture records, CI, generated-code workflows, migrations, and
deployment manifests are evidence when they affect slice safety.
- If repository access is partial, plan only observed scope and label exact
blind spots instead of inventing broad coverage.
## Quality gates
- Every path presented as existing was verified during reconnaissance.
- Path labels are load-bearing: every named path carries one of
`existing/read`, `proposed/new`, or `to-discover`. The plan's own
output file (`docs/plans/<slug>.md`) is labeled `proposed/new`
output, never presented as an already-existing file.
- Slice vocabulary is mandatory: the plan keeps the `## Slices` heading
and labels each slice `Slice N: <name>`. A plan without the literal
token `Slice` is incomplete, however good the prose reads.
- Every slice independently verifiable (tests/commands named).
- Each destructive or hard-to-reverse step has a demonstrated recovery plan
appropriate to its effects: safe reversal, backup restoration or forward fix.
Irreversible slices state the loss boundary and authorization gate; do not
invent a down migration or imply a code revert restores lost data.
- Uncertainty-collapsing slices precede their dependents.
- Decisions section covers every choice a reviewer would ask "why?" about.
- Acceptance criteria from the brief all appear in the definition of done.
- Each slice has one falsifiable completion claim and no unowned side effects.
- Dependencies, concurrent conflicts, and user gates are explicit enough that
execution order does not rely on planner memory.
## Stop conditions
- Executable plan delivered → stop for plan-only work; otherwise continue to
`pilot` within prior implementation authorization. Ask only for unresolved
material decisions or missing action authority.
- Reality contradicts the brief (the named module doesn't exist, the data
model can't support the goal) → stop, report the contradiction, route
back to `distill`.
- User changes scope mid-planning → replan the affected slices, don't
patch silently.
- Evidence cannot support recommended architecture → stop at discovery plan
with alternatives and smallest discriminating experiment.
- Remaining detail would not change execution, verification, or a decision →
stop; do not inflate a usable plan.
## Output contract
`docs/plans/<slug>.md` (provenance header `<!-- generated by masterplan on
YYYY-MM-DD -->`), sections per `references/plan-template.md`:
```markdown
# Plan: <title>
## Current state → Target state
## Decisions
## Slices (ordered, with dependency notes)
## Rollout, rollback, risks, checkpoints
## Definition of done
```
Chat summary: slice list (one line each), the 2–3 decisions that matter,
total risk in one sentence.
## Research basis
Read [references/research.md](references/research.md) when a decision depends on
an external standard, a numerical claim, or a fast-moving practice. The ledger
records what the source supports, what it does not support, and when to reverify.
Read [references/plan-template.md](references/plan-template.md) for durable
artifact shape. Read [references/planning-protocol.md](references/planning-protocol.md)
for slice contracts, decision records, discovery, or replanning.
Files in this package (4)
- SKILL.md 11 KB
- references/plan-template.md 4 KB
- references/planning-protocol.md 3 KB
- references/research.md 3 KB
Versions
The database has no other skills named masterplan.
Database snapshot: 13.11.2026 · package version d8ba3eafa25a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90invariants-and-non-goals
Identify the invariants, non-goals, and forbidden changes for the task and persist them, locking implementation boundaries before planning or coding. Use when impact analysis is done or mostly clear and the task may touch sensitive behavior, contracts, schema, or runtime. Do not… - 95find-unplanned-issues
Audit and clean the Remotion GitHub masterplan hierarchy. Use when finding open issues that lack a masterplan ancestor, identifying orphaned issues that need a parent, or recursively removing closed issues from the masterplan rooted at issue #9081. - 90writing-plans
Use when an approved change spans multiple dependent outcomes and needs a durable implementation sequence before coding. Do NOT use for small, obvious, reversible edits. - 100spec
Plan a non-trivial change before implementation. Use when work needs repository research, locked interfaces, security invariants, dependency-aware subtasks, executable acceptance criteria, and explicit approval. Consumes unknowns-map.md when available, writes plan.md, and stops… - 90implementation-plan
Produce an executable, repository-grounded implementation plan with bounded steps and verification gates. Use for multi-file features or risky changes before coding; not for trivial edits. - 90embedded-workbench
Use when starting any non-trivial coding task — loads risk-proportional workflows, engineering policies, and principles for embedded C/C++ firmware development. NOT for trivial single-line fixes, formatting-only changes, or read-only queries.