Implementation Plan

Implementation Plan

Purpose

Turn a large engineering change into a concrete execution plan that can be implemented step by step later.

This skill is for software delivery planning:

• architecture changes
• adding a new module
• migration work
• non-trivial refactors
• staged implementation of a feature

The output must be implementation-ready, not just a high-level idea list.

Use when

Use this skill when the user wants a plan for:

• architecture changes
• adding a new module or subsystem
• refactoring a significant code area
• migrations or staged replacements
• multi-step implementation with checkpoints

Typical trigger phrases:

• "давай сделаем план"
• "сделай план реализации"
• "составь поэтапный план"
• "спланируй рефактор"
• "сделай план архитектурного изменения"
• "prepare an implementation plan"
• "make a migration plan"
• "break this into milestones"

Do not use when

Do not use this skill for:

• personal scheduling
• study plans
• quarterly product roadmaps
• vague brainstorming with no implementation target
• direct implementation work when the user did not ask for planning
• bug fixing that only needs a local code change
• PR writing or review

Inputs

Expected inputs:

• target change
• current repository state
• relevant modules, interfaces, configs, and docs
• any explicit constraints from the user

Optional inputs:

• logs, failing tests, TODO notes, issue text, or design notes
• existing repo planning conventions
• performance, migration, or compatibility constraints

Outputs

Always produce:

1. a written plan document in the repository
2. the path to that document
3. a milestone-by-milestone execution plan for the user
4. assumptions, non-goals, and risks when relevant
5. lightweight validation for milestones that change behavior

Planning principles

The plan must be:

• minimal, not speculative
• self-contained enough to execute later
• implementation-oriented
• decomposed into isolated milestones
• balanced so milestones are reasonably similar in size
• explicit about validation
• explicit about what is out of scope

Do not add architectural layers, helper systems, abstractions, or migrations unless they are needed for the stated change.

Constraints

• Read the current code, docs, interfaces, and nearest AGENTS.md before proposing milestones.
• Prefer existing repository planning conventions when they already exist.
• Documentation is mandatory in the first and last milestones.
• Middle milestones should update docs only when contracts, config, usage, or operational behavior actually change.
• Validation should be lightweight by default: narrow unit tests, smoke tests, focused integration checks, static validation, or schema checks.
• Avoid planning heavy validation unless the requested change truly requires it.
• Keep scope anchored to the requested change; do not silently expand it.

Procedure

1. Inspect current state first. Read the narrowest relevant code, tests, docs, configs, and interfaces. Understand:

   • what exists now
   • what must change
   • what must remain stable
   • what constraints are already present

2. Define the target clearly. Before writing milestones, identify:

   • desired outcome
   • hard constraints
   • compatibility requirements
   • explicit non-goals
   • any unresolved assumptions

3. Choose where to write the plan. Prefer an existing repository convention if one exists. Otherwise:

   • use PLANS.md when the repo already treats planning as a shared execution artifact
   • or create docs/plans/<short-slug>.md for change-specific plans

4. Start documentation in the first milestone. The first milestone must include creating or updating the plan document with:

   • problem statement
   • target outcome
   • scope
   • non-goals
   • constraints
   • affected components
   • milestone list

5. Decompose into milestones. Break the work into isolated milestones that:

   • each produce a meaningful intermediate state
   • minimize cross-milestone entanglement
   • are reasonably similar in size
   • can contain substeps when needed
   • avoid mixing unrelated work

6. For each milestone, include:

   • goal
   • affected files, components, or interfaces
   • concrete implementation steps
   • substeps when necessary
   • lightweight validation
   • exit criteria
   • optional documentation updates if that milestone changes contracts or usage

7. Keep validation lightweight. Prefer:

   • narrow unit tests
   • smoke tests
   • static validation
   • focused integration checks
   • interface, schema, or config validation

   Avoid heavy or expensive validation unless clearly required:

   • large end-to-end suites
   • long training jobs
   • full benchmark pipelines
   • broad regression runs

8. Use a spike milestone only when uncertainty is real. If a major unknown blocks correct decomposition, add an early spike or proof-of-concept milestone. It must be narrow and must answer a concrete uncertainty, not become open-ended exploration.

9. Keep milestone size balanced. If one milestone is too large, split it. If a milestone is too small and has no standalone value, merge it into a neighboring milestone.

10. End with closure. The final milestone must include:

• final documentation reconciliation
• cleanup of temporary transitions if applicable
• final lightweight validation
• confirmation that the plan document reflects the final intended shape

Decision rules

Minimality rule

Do not invent additional architecture, wrappers, adapters, services, or abstractions unless they are necessary for this exact change.

Isolation rule

Prefer milestones that can be implemented and validated independently.

Validation rule

Every milestone that changes behavior should include the smallest credible validation proving that the logic is still correct.

Documentation rule

Documentation is mandatory in the first and last milestones. In middle milestones, update docs only if interfaces, config, usage, or operational behavior changed.

Unknowns rule

If a key unknown could invalidate the plan, surface it explicitly and isolate it in an early spike or assumption note.

Scope rule

Keep the plan anchored to the requested change. Do not silently expand scope.

Optional subagent use

For large or cross-cutting changes, subagents are optional but useful before finalizing the plan:

• one repository-mapper subagent to find the affected modules, interfaces, configs, and existing docs
• one validation-surface subagent to identify cheap tests and verification points

Wait for both results, then write the final plan.

Do not spawn subagents for small, local changes.

Required plan document structure

The written plan document should contain:

• Title
• Goal
• Current state
• Desired end state
• Scope
• Non-goals
• Constraints or assumptions
• Affected components
• Milestones
• Validation strategy
• Risks or open questions
• Progress log (optional but recommended for living plans)

Definition of done

• A concrete plan document exists in the repository.
• Milestones are implementation-ready, isolated, and reasonably balanced.
• First and last milestones include documentation work.
• Behavior-changing milestones include lightweight validation.
• Non-goals, assumptions, and risks are explicit where they materially affect execution.
• The plan is minimal and avoids speculative architecture.

Final response format

Return a compact response in this structure:

• Plan document: <path>
• Goal: ...
• Scope: ...
• Non-goals: ...
• Milestones:
  1. ...
     • substep ...
     • validation ...
  2. ...
     • substep ...
     • validation ...
  3. ...
     • substep ...
     • validation ...
• Risks or assumptions: ...

Positive examples

Use this skill for:

• "давай сделаем план реализации"
• "составь план рефактора"
• "сделай поэтапный план миграции"
• "спланируй добавление нового модуля"
• "prepare an implementation plan for this architecture change"

Negative examples

Do not use this skill for:

• "распланируй мою неделю"
• "сделай roadmap на квартал"
• "почини этот баг"
• "закоммить и запушь"
• "ускорь этот модуль"