Skip to content
Skills Library
Programming · Planning

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.

Repository
Skills ↗
Licence
MIT
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
1
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. When to use
  2. When NOT to use
  3. Prerequisites
  4. Authority and planning modes
  5. Two planning depths
  6. Workflow
  7. Anti-bloat rules
  8. Tool selection / fallback
  9. Quality gates
  10. Stop conditions
Original SKILL.md headings · 219 lines, 1,555 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.