Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

masterplan

/masterplan

Układa kolejność wdrożenia zmiany na podstawie repozytorium: zależności, niezmienniki, pionowe wycinki, punkty wycofania, prace równoległe i decyzje nieodwracalne, zanim zacznie się kodowanie.

Repozytorium
Skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
19.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
1
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 19.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Układa kolejność wdrożenia zmiany na podstawie repozytorium: zależności, niezmienniki, pionowe wycinki, punkty wycofania, prace równoległe i decyzje nieodwracalne, zanim zacznie się kodowanie.

Oryginalny opis (EN)

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.

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 219 linii, 1 555 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (4)
  • SKILL.md 11 KB
  • references/plan-template.md 4 KB
  • references/planning-protocol.md 3 KB
  • references/research.md 3 KB

Wersje

W bazie nie ma innych skilli o nazwie masterplan.

Migawka bazy z 13.11.2026 · wersja paczki d8ba3eafa25a (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

  • 90invariants-and-non-goals
    Określa niezmienniki, cele wykluczone i zakazane zmiany dla zadania oraz zapisuje je, zanim zacznie się planowanie lub kodowanie.
  • 95find-unplanned-issues
    Audytuje i porządkuje hierarchię masterplanu Remotion na GitHubie: znajduje otwarte zgłoszenia bez przodka w masterplanie i rekurencyjnie usuwa zamknięte zgłoszenia z drzewa wokół #9081.
  • 90writing-plans
    Układa trwałą kolejność wdrożenia dla zatwierdzonej zmiany obejmującej zależne efekty, zanim zacznie się kodowanie.
  • 100spec
    Planuje nietrywialną zmianę przed kodowaniem: badanie repozytorium, zablokowane interfejsy, zadania i kryteria akceptacji.
  • 90implementation-plan
    Tworzy wykonalny plan wdrożenia oparty na repozytorium, z ograniczonymi krokami i bramkami weryfikacji przed kodowaniem.
  • 90embedded-workbench
    Ładuje procesy i zasady inżynierskie dla nietrywialnych zadań w C i C++ dla firmware'u, zanim zacznie się kodowanie.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.