Refine Implementation Plan

Turn an existing file-backed plan from a planning draft into a frozen, executable handoff for another Implementer. Treat planning-with-files as the unchanged persistence substrate and this skill as a temporary design-refinement layer.

Preserve the boundary

• Require $planning-with-files to be active in the same refinement entry or resume request. If it is not active, ask the user to invoke both skills and stop.
• Use the active plan directory already selected by planning-with-files. Do not create, select, move, rename, or migrate planning files.
• Never edit, copy, replace, or extend the installed planning-with-files skill, its templates, scripts, hooks, or references.
• Extend only the active plan's existing task_plan.md, findings.md, and progress.md.
• Follow the base skill's persistence, recovery, phase-status, error-recording, and reboot rules without restating or reimplementing them.
• Do not modify product code, configuration, tests, or generated artifacts while refining. Read-only repository inspection and planning-file edits are allowed.
• Use Designer and Implementer as roles. Do not bind the workflow to a particular model name.

Enter refinement

1. Confirm that the base skill resolved an active plan and that all three planning files exist. If any are missing, report the missing prerequisite and stop; do not repair the substrate yourself.
2. Read all three files completely. Answer the base skill's five reboot questions from disk rather than chat memory.
3. Inspect repository status and preserve all existing user changes. Establish the relevant code, tests, configuration, documentation, and public surfaces before proposing decisions.
4. Read planning-file-extensions.md, then idempotently add or update only the refinement sections it defines. Never create duplicate headings or parallel decision stores.
5. Set the workflow stage to exploring or refining, the current role to designer, and implementation authorization to no.

Run the refinement loop

Repeat this loop until the handoff gate passes:

1. Ground in evidence. Explore the current implementation, tests, conventions, and constraints. Record facts and source locations in findings.md as they are discovered.
2. Map contract gaps. Read decision-refinement.md. Check only relevant contract surfaces and classify each unresolved item as researchable fact, user decision, recommended default, implementation discretion, or out of scope.
3. Ask decision questions. Ask only questions whose answers change observable behavior, safety, data durability, compatibility, operations, or the structure of the implementation plan. Batch a small coherent set, provide a recommended default and concrete impact for each, and allow compact replies such as "all recommended."
4. Discuss before concluding. Treat user questions as joint exploration, not automatic rejection. Explain why the current recommendation exists, compare the new alternative under its valid conditions, and revise only when the evidence or user choice warrants it.
5. Write through immediately. After each answer, update the canonical outcome and phase impact in task_plan.md, detailed evidence and rationale in findings.md, and the chronological question round in progress.md. Use stable decision IDs instead of repeating paragraphs.
6. Rebuild the executable plan. Refine affected phases, dependencies, public contracts, failure behavior, defaults, migration or recovery rules, tests, and acceptance criteria. Leave local code-organization choices to the Implementer unless they are unusually fragile.
7. Recheck gaps. Mark replaced decisions superseded, reopen every affected phase, and continue. Do not hide unresolved choices inside implementation tasks.

Freeze the handoff

Read handoff-readiness.md in full before claiming that design is complete.

• Require every applicable readiness check to pass and every blocking decision to be confirmed or explicitly delegated.
• Obtain explicit user acceptance if the user has not already authorized the consolidated recommended choices.
• Set the workflow stage to implementation_ready, implementation authorization to yes, and identify the exact entry phase.
• Mark discovery and design phases complete, but do not mark the overall task complete or start implementation.
• Record remaining implementation discretion, verification expectations, and any per-phase commit convention.
• If the repository uses Git, recommend a focused design-checkpoint commit, but do not create it without user authorization.
• End with a concise handoff summary: active plan, entry phase, frozen decision range, open blocking decisions (none when ready), and next invocation ($planning-with-files without this skill).

If the user requests implementation while this skill is active, finish or validate the handoff and stop. Begin implementation in a later request using planning-with-files without this refinement skill.

Reopen design safely

When a later requirement changes a frozen contract:

1. Re-enter with both skills.
2. Change the workflow stage from implementation_ready or implementing back to refining.
3. Set implementation authorization to no while the affected contract is open.
4. Mark replaced decisions superseded, preserve their history, and reopen affected phases and acceptance criteria.
5. Repeat the refinement and handoff gates before implementation resumes.