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).

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

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

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