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

name, description

name	description
planner	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:

### 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:

### 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:

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:

# 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