| name | implementing-plans |
| description | Use when an approved implementation plan (a docs/rse/specs/plan-*.md file) exists and the next step is writing the code. Triggers: implement the plan, execute the plan, start building, run the plan. |
Implementing Plans
Execute a phased implementation plan faithfully, adapting to reality while
tracking progress in real-time and verifying each phase before advancing.
Interaction mode
This skill leans Direct by default. For the full Collaborative-vs-Direct protocol and override rules, see the Interaction Modes reference in the ai-research-workflows:using-research-workflows skill.
Checklist
Work through these in order and track them as tasks. Do not skip the review gates (steps 2, 5, and 7):
- Load the plan — read the plan and every file it references, completely
- Review the plan critically — raise concerns and confirm the working branch before writing code
- Implement one phase — follow the plan, adapt to reality, record every deviation
- Verify the phase — run automated checks; fix failures before advancing
- Pause for manual verification — wait for human confirmation before the next phase (except consecutive phases)
- Repeat steps 3–5 until every phase is done
- Confirm completion — all automated verification passes; nothing left unaccounted for on the branch
- Summarize & hand off — write
docs/rse/specs/implement-<slug>.md; route to ai-research-workflows:validating-implementations
Starting the skill
If no plan path is given, list ls -lt docs/rse/specs/plan-*.md .agents/plan-*.md 2>/dev/null and, in Collaborative
mode, ask which to implement; otherwise proceed (Direct).
When a plan is identified:
- Read the entire plan completely (avoid partial reads).
- Check for existing checkmarks (
- [x]) indicating completed work.
- Read all files mentioned in the plan completely — partial reads cause bugs.
- Understand the full scope, architecture, and dependency ordering before starting.
- Create a task for each phase to track progress.
Review the plan before building
Before writing any code, review the plan critically — do not treat it as
infallible:
- Sanity-check the approach. Identify questions, gaps, or concerns about the
plan's design, phase ordering, or success criteria. If anything looks wrong or
unclear, raise it with the user before starting — do not silently "fix" the
plan by improvising.
- Confirm the plan's assumptions still hold. Research code often depends on
data availability, specific dependency versions, random seeds, or a particular
environment. Verify these are in place; if a prerequisite is missing, surface
it now rather than failing mid-phase.
- Confirm the working branch. Never start implementation on
main/master
without explicit user consent — work on a feature branch. This is a hard stop
regardless of interaction mode.
If the plan is sound and the branch is set, proceed. If not, stop and resolve
the concerns first.
Implementation rules
- Implement one phase fully before moving to the next; do not jump ahead.
- After each phase: run automated verification, fix failures, then pause for
human manual verification before continuing.
- Follow existing code patterns — do not introduce inconsistencies.
- Edit the plan file in real-time: change
- [ ] to - [x] as tasks
complete. The user can track progress by reading the plan.
- Adapt to reality when the codebase differs from the plan, but communicate
every deviation before proceeding.
- When a phase produces a result, figure, metric, or trained artifact, capture
its provenance — environment, data version, seeds, exact commands — with
ai-research-workflows:ensuring-reproducibility so the result can be reproduced.
Handling mismatches
When what you find does not match the plan, stop and present the issue using
the mismatch report template in
references/templates.md.
Wait for user guidance before continuing. Let the user decide whether to adjust
the plan, proceed with original intent, or research further.
Verification after each phase
Automated verification
Run all commands listed in the plan's "Automated Verification" section. Document
results:
- Check passes — note the output.
- Check fails — investigate and fix before proceeding.
Manual verification (human required)
After automated checks pass, pause and inform the human:
## Phase [N] Complete - Ready for Manual Verification
### Automated Verification Results:
✅ `make test` — All 45 tests passing
✅ `pytest tests/` — 12 new tests added, all passing
✅ `mypy src/` — Type checking passed
### Manual Verification Needed:
Please perform these manual tests listed in the plan:
- [ ] [Manual step 1]
- [ ] [Manual step 2]
Let me know when manual testing is complete so I can proceed to Phase [N+1].
Wait for user confirmation before proceeding to the next phase.
Exception: consecutive phases
If instructed to execute multiple phases consecutively (e.g., "implement phases
1-3"):
- Run automated verification after each phase.
- Skip the manual-verification pause until the last phase.
- Still fix any automated check failures immediately.
- At the end, pause for human to do all manual testing.
Do NOT check off manual testing items in the plan until confirmed by the user.
Resuming work
If the plan has existing checkmarks (- [x]):
- Trust that completed work is done — do not re-implement completed phases.
- Pick up from the first unchecked item (
- [ ]).
- Re-verify previous work only if tests are failing, files are missing, or you
notice inconsistencies.
If you get stuck
- Make sure you have read all relevant files completely (no partial reads).
- Consider whether the codebase has evolved since the plan was written.
- Present the mismatch using the "Issue in Phase" template in
references/templates.md.
- Do not guess or make assumptions.
- Use sub-tasks sparingly — mainly for targeted debugging or exploring
unfamiliar territory, never for implementation itself.
Final implementation summary
Upon completing all phases, first confirm the work is genuinely done: every
phase's automated verification passes, no checklist item was silently skipped,
and you are not leaving changes on main/master. Then:
Generate filename — derive slug from plan filename:
plan-jwt-auth.md → implement-jwt-auth.md.
Read the template:
assets/implement-template.md
Fill all sections: plan reference, phases completed, files modified, tests
run, verification results (automated and manual), issues encountered, key
changes summary, remaining work, next steps.
Save to docs/rse/specs/implement-<slug>.md and confirm.
Present completion summary using the implementation completion summary
template in
references/templates.md.
Common Mistakes
- Diving into code without reviewing the plan — read and critically review
the whole plan first; raise design or assumption concerns, and confirm you are
on a feature branch (not
main/master), before writing any code.
- Implementing multiple phases before verifying — always run automated
checks and pause for manual verification after each phase before advancing.
- Not pausing for manual verification — automated checks passing is not
sufficient; stop and explicitly request human confirmation of manual steps.
- Checking off manual items the user has not confirmed — do not mark manual
verification tasks
[x] until the user reports them done.
- Plowing past a plan/reality mismatch — when the codebase differs from the
plan, stop and present the mismatch report; never silently adapt and continue.
- Partial file reads causing bugs — always read all files mentioned in the
plan completely before starting implementation.
Cross-references
Follows the ai-research-workflows:planning-implementations skill; verify with
ai-research-workflows:validating-implementations. For research code, capture provenance with
ai-research-workflows:ensuring-reproducibility and robustness with ai-research-workflows:hardening-research-code.
Quality checklist
Before marking a phase as complete:
Before marking implementation as complete:
