Planner

Planner

Use this skill only when the user explicitly requests this skill or explicitly asks for a plan-first workflow. The goal is to prevent premature implementation, make assumptions visible, and give the user a concrete plan they can review, revise, or approve.

When To Use

Use this skill only when the user explicitly names this skill or clearly asks for a plan-first workflow for:

• a feature addition or behavior change
• a bug fix or regression fix
• implementation work that may touch code, tests, docs, build scripts, or runtime configuration
• a plan-first workflow, working document, or approval step before changes

Do not infer this skill from ordinary software change requests. Do not use it for read-only explanations, simple command output, pure code review, implementation requests without an explicit planning step, or explicitly scoped verification-only work unless the user asks for a plan.

Core Rule

Do not edit production code before the user approves the plan.

During the planning phase, inspect files, read specifications, trace the current implementation, and run non-mutating commands as needed. If a browser, desktop app, external service, or other side-effectful tool is needed to confirm behavior, explain why it is needed and ask the user before using it.

If the user explicitly overrides part of this workflow, follow the user's latest instruction. For example, if the user says not to commit, do not commit even if this skill normally includes commit steps.

Planning Workflow

1. Inspect the current system.

   • Read the relevant code paths, tests, specs, README files, and project instructions.
   • Identify the current contract before proposing changes.
   • For bugs, find the likely cause before proposing a fix.

2. Write an implementation plan.

   • Save the plan as a Markdown file under docs/plans/.
   • If the project already uses another working-docs directory, use that directory's plans/ subdirectory.
   • Name the file yyyy-mm-dd-{plan-name}.md.
   • Write the plan in the user's preferred language.

3. Validate the plan with a subagent.

   • Spawn a subagent after writing the plan and ask it to independently review the plan's validity.
   • Revise the plan when the review identifies an issue.
   • If the plan changes, spawn a new subagent and repeat the review until no further revision is needed.

4. Ask for user approval.

   • Summarize the plan location and the key implementation choices.
   • Ask the user whether to proceed or revise the plan.
   • Do not start code changes until the user confirms.

5. Execute only after approval.

   • Follow the approved plan.
   • Keep the plan checklist updated as work progresses.
   • If new evidence invalidates the plan, stop and explain the needed adjustment before expanding scope.

Independent Plan Review

Ask the subagent to verify:

• whether the plan covers every part of the user's request
• whether the plan contains contradictions or risks the user may have missed
• whether the plan makes decisions without the user's permission

Do not flag minor details that do not affect logic or decisions that are ordinarily accepted without explicit permission.

Keep the review context independent:

• If the user supplied a separate request document, pass its path to the subagent instead of a request summary. Also pass the plan path.
• If the request exists only in the prompt, include the original request as faithfully as possible. Avoid replacing it with conclusions or a narrowed summary.
• Ask the subagent to review the source request and plan directly without providing the expected findings, suspected problems, or prior review conclusions.

Plan Contents

Every plan must include:

• Goal and current behavior
• Relevant files and code locations
• Current contract or specification evidence
• Proposed changes by file
• TDD plan with concrete test names and scenarios
• Expected behavior after the change
• Expected side effects and compatibility risks
• Verification steps, including tests, build/check commands, and any manual/browser checks
• TODO checklist that can track planning, implementation, verification, documentation, and commit steps

If the project is managed with Git, every plan must also include a Commit Plan section. For each atomic work unit, specify:

• the paths of files to create or modify, including the relevant content and location within each file
• a concise purpose and description of the work
• the expected commit point
• the expected commit message

For bug fixes, also include:

• Reproduction path or observed symptom
• Root cause hypothesis or confirmed cause
• Why the proposed fix addresses that cause

TDD Expectations

Feature work and behavior changes should follow this sequence:

1. Add or update a unit test that captures the intended behavior.
2. Run the test and confirm it fails for the expected reason.
3. Implement the minimal code needed to pass the test.
4. Run the test and confirm it passes.
5. Refactor if needed while keeping tests green.

If a unit test is not practical, state why in the plan and choose the closest reliable verification path.

Checklist Management

The plan file must contain a TODO checklist.

During execution:

• Check off items as they are completed.
• Before declaring completion, verify every checklist item.
• If an unchecked item was implemented but not marked, update the checklist.
• If an unchecked item was not implemented, complete it or explain why it was intentionally left out.

Commit Policy

By default, commit immediately after each completed atomic work unit, not only at the end. Do not postpone commits until several work units have modified the same files; delayed commits may make the intended atomic boundaries impossible to preserve.

Before each commit:

• Run the relevant build, check, or test command.
• Fix failures before committing.
• Keep commits scoped to one atomic unit of behavior.

Do not commit when the user says not to commit, when approval has not been granted, or when the repository's local instructions prohibit commits.

Asking Questions

Ask questions only when the answer cannot be discovered from the repo and a reasonable assumption would be risky.

When asking a question:

• First explain the context that makes the decision necessary.
• State the impact of the choice.
• Then ask the concise question.

The user should be able to understand why the question matters from the surrounding explanation, not from hidden reasoning.

Output Style

Be concrete and evidence-based.

• Prefer file paths, function names, test names, command names, and observed behavior over general statements.
• Separate planned work from completed work.
• Do not claim that code, tests, browser checks, or commits are done unless they actually ran or happened.
• If verification was skipped or blocked, say so directly.