implementing-plan

name	implementing-plan
description	Implement technical plans from thoughts/shared/plans with verification. Use when executing approved implementation plans, resuming partially completed plans, or when the user mentions execute plan or resume plan.

Implementing Plans

Execute approved technical plans from thoughts/shared/plans/ with verification at each phase.

Workflow Context

This skill executes plans produced by creating-plan:

1. creating-plan — Research, design, write the plan
2. implementing-plan (this skill) — Execute phase-by-phase with verification
3. validating-plan — Audit the implementation against the plan

The plan file at thoughts/shared/plans/ is the contract. Success criteria in the plan are executed literally — automated verification commands are run as written.

Test-Driven Implementation

MANDATORY: Apply the test-driven-development skill's RED-GREEN-REFACTOR cycle for every unit of production code written within a phase.

The procedure for each unit of work:

1. Write a failing test (RED)
2. Write minimal code to pass (GREEN)
3. Refactor while keeping tests green
4. Repeat for the next behavior

After all TDD cycles in the phase are complete, run the phase's automated verification commands as the final gate.

Resolving conflicts with the plan: If the plan says "no tests needed", evaluate independently. The plan may be wrong — verify by reading existing test files. Apply TDD unless the code meets ALL of these criteria:

1. Zero conditional logic (no if/else, no switches, no ternaries, no loops with conditions)
2. Zero data transformation (no mapping, filtering, formatting, restructuring)
3. The function is a pure pass-through that only calls other already-tested functions with static arguments

"Wiring", "integration-level", "mostly delegation", and "would require too many mocks" are NOT valid reasons to skip TDD. If mocking is hard, that's a design signal — simplify the interface or extract testable units.

When skipping TDD: Document the skip in the phase completion message with the specific criteria met (1-3 above). If you cannot clearly articulate which criterion applies, you must write tests.

Getting Started

When given a plan path:

1. Read the plan completely - check for existing checkmarks (- [x])
2. Read ALL files mentioned in the plan without limit/offset
3. Read existing test files for every module the plan modifies (use glob: **/__tests__/*, **/*.test.*, **/*.spec.* near changed files). This is mandatory — never assume "no tests exist" without checking.
4. Understand how the pieces fit together
5. Create a todo list to track progress
6. Begin implementation of the first uncompleted phase only

If no plan path provided, ask for one:

Which plan would you like to implement? Please provide the path.
Tip: `ls -lt thoughts/shared/plans/ | head`

Implementation Workflow

Following the Plan

Plans are carefully designed, but reality can be messy:

• Follow the plan's intent while adapting to discoveries
• Implement each phase fully before moving to the next
• Verify work makes sense in the broader codebase context
• Update checkboxes in the plan as sections complete
• Maintain a detailed todo list tracking each task step-by-step

Handling Mismatches

When reality doesn't match the plan:

1. STOP and think deeply about why
2. Present the issue clearly:

Issue in Phase [N]:
Expected: [what the plan says]
Found: [actual situation]
Why this matters: [explanation]

How should I proceed?

Phase Implementation Workflow

Before writing any production code for a phase:

1. Read existing test files for the modules being changed (if not already read in Getting Started)
2. For each change block in the phase, read only the Testable Behaviors section — do NOT read the Reference Implementation yet
3. For each testable behavior bullet, execute one RED-GREEN-REFACTOR cycle:
   • RED: Write one failing test for that behavior. Run it. Confirm it fails for the right reason.
   • GREEN: Write the minimal production code to pass it. Run it. Confirm it passes.
   • REFACTOR: Clean up. Run tests. Stay green.
4. Only after all behavior bullets have passing tests, read the Reference Implementation and reconcile — adjust your implementation if it diverges from the plan's intent, but do not delete passing tests.
5. Proceed to the phase completion checklist.

How to Extract Work Items from a Plan Change Block

A change block looks like:

##### Testable Behaviors (RED tests)
- `cutoff empty` → `isEnvCreatedAfterCutoff` returns `true`
- `createTime after cutoff` → returns `true`
- `createTime before cutoff` → returns `false`
- `createTime null + cutoff set` → returns `false` (safe fallback)

##### Reference Implementation
[code]

Map this to a work queue:

1. def "isEnvCreatedAfterCutoff: cutoff empty returns true"() → RED → GREEN
2. def "isEnvCreatedAfterCutoff: createTime after cutoff returns true"() → RED → GREEN
3. def "isEnvCreatedAfterCutoff: createTime before cutoff returns false"() → RED → GREEN
4. def "isEnvCreatedAfterCutoff: null createTime with cutoff set returns false"() → RED → GREEN

Each bullet is one test. Complete all cycles for this change block before moving to the next.

Phase Completion Checklist

After implementing a phase (all TDD cycles done), follow this checklist in order:

1. Run automated success criteria checks (compile, tests, etc.)
2. Fix any issues found
3. Update checkboxes in the plan file for completed automated verification items
4. Update progress in todo list
5. STOP and present the verification message (see below)
6. WAIT for user confirmation before starting next phase

Verification Message Template

Phase [N] Complete - Ready for Manual Verification

Automated verification passed:
- [List automated checks that passed]

Please perform the manual verification steps listed in the plan:
- [List manual verification items from the plan]

Let me know when manual testing is complete so I can proceed to Phase [N+1].

Before Starting Any New Phase - Ask Yourself:

1. Did the user explicitly confirm the previous phase is complete?
2. Did the user explicitly request multiple phases?

If BOTH answers are NO → Do not proceed. Wait for user input.

Do NOT check off manual testing steps in the plan until confirmed by the user

Resuming Work

If the plan has existing checkmarks:

• Trust that completed work is done
• Pick up from the first unchecked item
• Verify previous work only if something seems off

When Stuck

When something isn't working as expected:

1. Read and understand all relevant code first
2. Consider if the codebase evolved since the plan was written
3. Present the mismatch clearly and ask for guidance

Use tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory.

Guidelines

One Phase at a Time: Stop after each phase. Wait for confirmation. This is the default.

Follow Intent: The plan is your guide, but judgment matters. Adapt to discoveries while preserving the plan's goals.

Be Thorough: Read files completely. Understand context before making changes.

Communicate Clearly: When things don't match, explain why and ask for direction.

Track Progress: Update checkboxes in the plan and maintain todo list for visibility.

Path Handling

• The thoughts/searchable/ directory contains hard links for searching
• Always use canonical paths when referencing or writing files
  • Use: thoughts/shared/prs/123.md
  • Not: thoughts/searchable/shared/prs/123.md