Implementation Planning

Implementation Planning

Create an implementation plan that another developer or coding agent can execute without having to rediscover the codebase or make important architectural decisions.

This skill owns planning only.

It must not duplicate the responsibilities of:

• brainstorming
• executing-plans
• test-driven-development
• systematic-debugging
• requesting-code-review
• verification-before-completion

Purpose

A good plan must answer:

1. What behavior is changing?
2. How does the relevant behavior work today?
3. What existing code can be reused or extended?
4. What is the smallest coherent change?
5. In what order should the change be implemented?
6. How will each meaningful step be validated?
7. What risks, dependencies, or compatibility concerns matter?
8. Is the plan internally consistent and actually useful to execute?

The plan must be grounded in repository evidence, not framework assumptions.

When to use

Use this skill when one or more of these are true:

• the task spans multiple files, modules, layers, or responsibilities;
• existing behavior must be understood before implementation;
• multiple implementation approaches are plausible;
• the change affects business rules, permissions, persistence, integrations, or public contracts;
• there is meaningful regression or data risk;
• another agent or developer will execute the work;
• the user explicitly asks for an implementation plan.

Do not force a large plan for an obvious, isolated change.

Relationship with other skills

Use the dedicated skills instead of reproducing their workflows here.

Before planning

Use brainstorming first when:

• requirements are ambiguous;
• product behavior is undecided;
• major technical alternatives must be compared;
• trade-offs must be resolved before implementation can be planned.

implementation-planning should receive sufficiently defined behavior.

After planning

Use executing-plans to implement an accepted plan.

During implementation:

• use test-driven-development when tests are practical and behavior is changing;
• use systematic-debugging when failures or unexplained behavior appear.

After meaningful implementation:

• use requesting-code-review to review the resulting code;
• use verification-before-completion before claiming the task is complete.

This skill may reference those later validation activities in the plan, but it must not perform their full workflow.

Planning workflow

1. Understand the requested outcome

Reduce the task to an observable goal.

Capture:

• requested behavior;
• important constraints;
• explicit non-goals;
• acceptance expectations already provided by the user or repository.

Do not redesign the task during planning.

If the requested behavior is still materially ambiguous, defer to brainstorming instead of inventing requirements.

2. Investigate the repository

Before proposing changes:

1. Read applicable AGENTS.md instructions.
2. Locate the entry point for the requested behavior.
3. Trace the relevant execution path.
4. Inspect nearby implementations solving similar problems.
5. Search for reusable components, services, actions, helpers, validators, schemas, model methods, queries, policies, utilities, or abstractions.
6. Inspect relevant tests.
7. Identify repository-specific validation commands when readily discoverable.
8. Identify constraints that materially affect the change.

Investigate only as far as needed to produce a reliable plan.

Do not perform a general architecture audit.

3. Apply reuse-first reasoning

Before proposing new code, determine whether the required responsibility already exists.

Prefer, in this order:

1. reuse an existing implementation;
2. extend an existing implementation;
3. compose existing primitives;
4. extract genuinely shared behavior;
5. create a new implementation only when necessary.

Before proposing a new controller, service, action, repository, model method, validator, schema, DTO, middleware, helper, utility, component, hook, or abstraction:

• search for equivalent behavior;
• search for similar behavior;
• inspect the local architectural pattern;
• explain why reuse or extension is insufficient if new code is needed.

Do not introduce an abstraction solely because two code fragments look similar.

4. Separate evidence from decisions

Important planning information should be classified as:

• Confirmed — verified in repository code, tests, configuration, documentation, or task requirements.
• Decision — an implementation choice needed to perform the task.
• Unknown — information that materially affects the plan and is not yet confirmed.

Resolve repository-answerable unknowns before finishing the plan.

If an unknown cannot be resolved and does not prevent planning, add an explicit verification point to the relevant plan step.

Do not disguise guesses as facts.

5. Design the smallest coherent change

The plan should describe the minimum set of coordinated changes needed to produce the requested behavior.

Do not:

• create one step per file;
• mirror framework layers mechanically;
• add speculative abstractions;
• include unrelated refactors;
• expand scope because nearby code could also be improved.

Group changes by observable behavior or dependency boundary, not by file type.

A normal plan should usually contain about 2 to 5 implementation steps.

Use more only when separate migration, deployment, rollback, integration, or dependency boundaries justify it.

6. Define validation intent

The plan must say how each meaningful step will be proven correct, but should delegate the detailed testing workflow to the appropriate skills.

For each step, identify the expected validation category, such as:

• existing test to update;
• regression test to add;
• focused automated check;
• integration scenario;
• authorization/security scenario;
• migration/data check;
• UI/manual scenario when automation is insufficient.

When implementation begins:

• test-driven-development owns the detailed Red → Green → Refactor workflow;
• verification-before-completion owns final execution of the repository's verification suite.

Do not claim planned validations have already passed.

Required plan format

Use this structure and omit optional sections that add no value.

Plan: [observable outcome]

Summary

• Task: [reference, issue, or concise task name]
• Branch: [branch name to use or create for the implementation]
• Branch origin: [base branch, ref, or commit from which the branch will be created]
• Goal: [observable result]
• Scope: [what will change]
• Out of scope: [only important boundaries]

The plan must always identify the implementation branch and its origin. If the branch already exists, record its exact name and current base/origin. If it does not exist yet, record the proposed name and the exact branch, ref, or commit from which it must be created. Planning does not create the branch; it documents the branch decision for the execution handoff.

Current behavior

Summarize the confirmed current execution path relevant to the task.

When useful:

[input] → [validation/authorization] → [business logic] → [persistence/integration] → [output]

Keep this focused on the behavior being changed.

Repository evidence

List only evidence that materially shapes the plan.

Examples:

• path::symbol already owns the relevant responsibility;
• a similar feature uses a particular pattern;
• an existing validator/helper/component can be extended;
• an existing test establishes current behavior;
• repository instructions impose a constraint.

Avoid dumping exploratory notes.

Decisions and constraints

Include only decisions that materially affect implementation.

Use stable IDs when useful:

• D1 — [decision]: [choice and reason]
• D2 — [constraint]: [constraint and consequence]

Typical examples:

• authorization boundary;
• tenant/ownership enforcement;
• backward compatibility;
• migration strategy;
• transaction boundary;
• public API compatibility;
• external integration behavior.

Change map

List confirmed locations that participate in the change.

Rules:

• prefer exact symbols when known;
• do not list speculative files;
• do not list new files until reuse/extension has been considered;
• reference map IDs from implementation steps instead of repeating paths.

Implementation steps

Each step must produce one coherent, observable result.

B01 — [observable result]

• Objective: [what becomes true]
• Depends on: [decision/block/dependency or none]
• Change map: M01, M03
• Implementation: [concise description of the smallest required change]
• Validation intent: [what must prove this step correct]
• Complete when: [observable completion criterion]

Add more blocks only when they are independently meaningful.

Step design rules

A good step:

• represents behavior, not a file edit;
• has a clear completion condition;
• can be validated;
• does not contain unrelated cleanup;
• references existing code where reuse is expected;
• makes dependencies on earlier steps explicit.

Bad step:

Modify UserController.php.

Better step:

Allow an authorized user to update the new preference through the existing profile update flow, preserving the current authorization boundary.

Acceptance criteria

Translate the task into observable outcomes.

Acceptance criteria must describe behavior, not implementation details.

Risks and dependencies

Include only concrete task-specific concerns.

Omit this section when there are no meaningful risks.

Execution handoff

End the plan with the intended next workflow.

Examples:

• Next: execute with executing-plans.
• During implementation: use test-driven-development for B01 and B02.
• If B02 exposes unexplained existing behavior, switch to systematic-debugging.
• After implementation: requesting-code-review → verification-before-completion.

Do not execute those workflows as part of this skill.

Plan quality gate

Before returning a plan, validate the plan itself.

Evidence

• Is the described current behavior supported by repository evidence?
• Were relevant project instructions inspected?
• Were similar implementations searched for?
• Are proposed new abstractions justified?
• Are speculative files excluded?

Coherence

• Does every implementation step contribute directly to the requested outcome?
• Are dependencies between steps correct?
• Does the sequence make implementation practical?
• Are decisions consistent across all steps?
• Does the change map match the implementation steps?

Scope

• Is the plan limited to the requested task?
• Are unrelated refactors excluded?
• Is the proposed change the smallest coherent solution?
• Is anything included merely because it would be "nice to improve"?

Reuse

• Does the plan reuse or extend existing behavior where appropriate?
• If new code is proposed, is the reason clear?
• Does the plan follow actual repository conventions instead of assumed framework conventions?

Validation

• Does every meaningful step have a validation intent?
• Do acceptance criteria describe observable behavior?
• Are important negative or regression scenarios included when relevant?
• Are planned validations clearly distinguished from already executed checks?

Executability

Ask:

Could another capable developer or agent implement this plan without having to rediscover the architecture or make an unresolved major design decision?

If not, improve the plan before returning it.

Usefulness

Ask:

Does every section help implementation or validation?

Remove:

• duplicated information;
• generic software advice;
• architecture explanations unrelated to the change;
• speculative risks;
• ceremonial sections with no actionable value.

The final plan should be concise enough to follow during implementation and specific enough to prevent avoidable rediscovery or architectural drift.

Final behavior

Return only a plan that has passed the quality gate.

If a safe plan cannot be produced because a material requirement is unresolved:

• identify the exact unresolved point;
• explain why it changes the implementation;
• use brainstorming when the uncertainty is a design/product decision;
• investigate further when the answer should exist in the repository.

Do not invent certainty to complete the plan.