penpot/.agents/skills/planner/SKILL.md

---
name: planner
description: Read-only planning and architecture analysis — produce a structured implementation plan with task breakdown, acceptance criteria, sizing, and checkpoints. Always output to the user with the plan, suggested save path and the next steps.
---

# Planner

Produce a plan that another engineer or agent can execute without guessing.

## When to Use

- The user asks for a plan, design, or analysis of a feature or bug.
- The user wants to understand which parts of the codebase a task will touch.
- The user needs a step-by-step implementation plan with file paths, function
  names, and test strategy.
- The user asks "how would I implement X?" or "what's involved in fixing Y?".
- The user is about to start non-trivial work and wants a bite-sized task
  breakdown.
- A task feels too large or vague to start.
- Work needs to be parallelized across multiple agents or sessions.

Do not use for a small change with obvious scope or an existing executable plan.

## CRITICAL: Required Reading Before Planning

Before drafting any plan, work through the project's own guidance:

1. Read `critical-info` (`.serena/memories/critical-info.md`) — the entry point
   that describes the monorepo structure and module dependency graph.
2. From `critical-info`, identify which modules your task affects.
3. Read each affected module's core memory, e.g. `mem:frontend/core`,
   `mem:backend/core`, `mem:common/core`, `mem:exporter/core`,
   `mem:render-wasm/core`. Follow `mem:` references deeper as needed.
4. For each affected module, note its lint, format, and test commands so the
   plan can include concrete verification steps.

Skipping this step is the #1 cause of incorrect or incomplete plans.

## Constraints

- You are **analysis-only** — never create, edit, or delete source code. The
  only file you may write is the plan itself, and only when the command or
  user explicitly instructs you to save it.
- You do **not** run builds, tests, linters, or any commands that modify state.
- You do **not** create git commits or interact with version control.
- You do **not** execute shell commands beyond read-only searches (`rg`, `ls`,
  `find`, `cat`, `bat`).
- Your output is a structured plan or analysis, ready for handoff to an
  engineer agent or developer.

## Planning Process

1. Define the problem, desired outcome, constraints, and exclusions.
2. Trace the current behavior through the affected modules.
3. Map dependencies and choose an implementation order that builds foundations
   before their consumers.
4. Identify open product or architecture decisions. Resolve implementation
   details from existing conventions when they do not affect public behavior.
5. Identify edge cases, security and data risks, performance bounds, breaking
   changes, and external dependencies.
6. Split the work into small, ordered tasks. Prefer complete testable slices
   over unrelated layer-wide batches. Apply DRY and KISS to the proposed
   implementation.
7. Define exact acceptance criteria and verification for every task.
8. Add a checkpoint after every two or three tasks in a longer plan.
9. State which tasks can run in parallel and which must remain sequential.

## Task Format

Each task follows this structure:

```markdown
### Task [N]: [Short descriptive title]

**Description:** One or two paragraphs explaining what this task accomplishes.
Should be clear and concise.

**Rationale:** Why this task exists and why this approach over the obvious
alternatives — design decisions, trade-offs, constraints discovered during
analysis. One or two sentences; skip only if genuinely trivial.

**Code sketch (optional):** Signature-, type-, or shape-level example when the
intended interface is non-obvious. Keep it short — a skeleton that fixes the
contract (function signature, model fields, error shape), never a full
implementation. Omit when the task is mechanical.

**Acceptance criteria:**
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]

**Verification:**
- [ ] Relevant tests pass (module-specific test command).
- [ ] Lint/formatter passes (module-specific check command), if applicable.
- [ ] The core flow works end-to-end, if applicable.

**Dependencies:** [Task numbers this depends on, or "None"]

**Files likely touched:**
- `path/to/file.clj`
- `path/to/file_test.clj`

**Estimated scope:** [XS: 1 file | S: 1-2 files | M: 3-5 files | L: 5+ files]
```

Use commands from `mem:testing` and affected module memories. Never substitute
generic text such as "run the tests" when the project documents an exact
command.

When possible, design each task with TDD in mind: acceptance criteria double as a test
list, and the natural first step of the task is writing those tests before the
implementation. Some tasks resist this (config, migrations, pure wiring) — for those, keep
the usual verification steps.

## Task Sizing

| Size | Files | Scope | Example |
|------|-------|-------|---------|
| **XS** | 1 | Single function, config change, or schema tweak | Add a validation rule |
| **S** | 1-2 | One handler or component method | Add a new RPC endpoint |
| **M** | 3-5 | One vertical feature slice | Bookmark CRUD with tests |
| **L** | 5-8 | Multi-component feature | Search with filtering and pagination |
| **XL** | 8+ | **Too large — break it down further** | — |

Split a task when it contains independent outcomes, spans unrelated systems, or cannot be
completed and verified in one focused session (if a task is XL, it should be broken into
smaller tasks; agents perform best on S and M tasks).

## Task order and checkpoints

Arrange tasks so that:

1. Dependencies are satisfied (build foundation first)
2. Each task leaves the system in a working state
3. Verification checkpoints occur after every 2-3 tasks
4. High-risk tasks are early (fail fast)

Add explicit checkpoints with the relevant module commands:

```markdown
### Checkpoint: After Tasks 1-3
- [ ] Relevant tests pass (module-specific command).
- [ ] The relevant build or compilation passes, if applicable.
- [ ] The core flow works end-to-end.
```

## Output Format

The plan is always delivered in the response so the user sees it regardless
of which agent is running the skill. File writes follow `Constraints` —
by default announce the path instead of writing.

Announce the save path `.agents/plans/YYYY-MM-DD-<slug>.md` (today's date,
lowercase hyphen-separated slug, e.g. `2026-09-10-add-batch-get-profiles`;
an explicit user path wins).

### Derived plans

Never invent a fresh slug when the plan derives from an existing one.
The derived name is `<parent-basename>` plus one suffix per level,
joined with `--` (double hyphen; single hyphens already separate
slug words, so `--` marks where the derivation starts). The parent
name is never edited, and no new date is added — the parent prefix
already carries its date, which keeps parent and derivatives adjacent
in `ls`. Record the real creation date inside the plan (`Created:`).

Valid names match:

```
^\d{4}-\d{2}-\d{2}-[a-z0-9-]+(--(review-\d{2}|task-\d{2})(-[a-z0-9-]+)?)*\.md$
```

- `review-NN` — a new plan addressing findings of a `review-code` or
  `review-plan` on already-implemented work. `NN` counts reviews of
  that parent from `01`. Example: parent
  `2026-09-14-paste-before-init-crash.md` →
  `2026-09-14-paste-before-init-crash--review-01.md`,
  then `--review-02.md`.
- `task-NN-<short-slug>` — sub-plan for task `NN` of a high-level
  roadmap plan. `NN` is the roadmap task number. Example: parent
  `2026-09-20-upload-pipeline-roadmap.md` →
  `2026-09-20-upload-pipeline-roadmap--task-01-chunk-upload.md`.
  Levels chain: `...--task-02-gc--review-01.md`.

Never use `v2`, `final`, `new`, or `fix2` as suffixes. Keep the
optional short slug to 3-4 lowercase hyphen-separated words.

Every derived plan opens its `Context` with:

```markdown
Parent: `<parent-basename>.md`
Source: review-code over `<commit>` (branch `<branch>`) | task `NN` of roadmap `<parent-basename>.md`
Created: YYYY-MM-DD
```

End the response by suggesting the next steps: `/review-plan` to get a second
opinion on the plan and `/implement-plan` to execute it.

### Plan Structure

Use this document shape:

```markdown
# Plan: Title

Status: draft | reviewed | done
Review Log:
- YYYY-MM-DDTHH:MM:SSZ — <what changed and why, one line per entry>

## Context
## Affected Modules
## Architecture Decisions
## Risks and Considerations
## Approach
## Task List
## Verification and Testing
## Parallelization
## Open Questions
```

`Status` and `Review Log` are write-restricted metadata, not free text:

- `make-a-plan` creates every plan with `Status: draft` and an empty
  log. `reviewed` never means "a review was emitted" — it means
  "review feedback was incorporated". A plan approved with no changes
  goes `draft` → `done` without passing through `reviewed`.
- Only a user-triggered apply step writes them before implementation:
  when the user says to apply `review-plan` findings, `make-a-plan`
  applies the changes, flips to `reviewed`, and appends one UTC
  ISO 8601 line describing what changed.
- `implement-plan` flips to `done` on completion and appends one line
  with the issue URL when one exists (standalone mode); otherwise
  just `done`. Never record commit hashes — they rot on amend/rebase
  and git already links the commit.
- The log is append-only: never rewrite or delete lines.
- `review-plan` and `review-code` never write these fields.

Omit empty sections only when they do not apply. Every implementation task
still requires acceptance criteria, verification, dependencies, likely files,
and scope.

When the plan is purely analytical (e.g. a code review or feasibility study
with no implementation), skip the **Approach** and **Task List** sections and
lead with **Findings** instead, keeping the rest of the structure.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I'll figure it out as I go" | That's how you end up with a tangled mess and rework. 10 minutes of planning saves hours. |
| "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
| "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. |

## Verification Checklist

Before delivering the plan, confirm:

- [ ] Every task has acceptance criteria
- [ ] Every task has a verification step
- [ ] Task dependencies are identified and ordered correctly
- [ ] No task is XL or larger — break it down instead
- [ ] Checkpoints exist after every 2-3 tasks
- [ ] The response states the plan's path (saved or suggested) and suggests
      `/review-plan` and `/implement-plan`
- [ ] The plan is ready for human review