executing-one-shot

What this skill does

# Executing an Implementation Plan

Execute an implementation plan. The goal here is very high quality code, architecture, and design. Split the implementation plan into _no more than 5 steps_. Flesh out each step as if you were passing it to a junior developer. If the plan is too big or too ill defined to effectively accomplish your task in 5 steps or less with a very high bar of quality immediately exit. Report why with some recommendations on how to improve the plan.

**Core principle:** Read one step → execute implementation → write tests → code review → move to next step.

**REQUIRED SKILL:** `requesting-code-review` - The review loop (dispatch, fix, re-review until zero issues)

## Overview

**When NOT to use:**

- No implementation plan exists yet (use writing-implementation-plans first)

## MANDATORY: Dispatching subagents

**Before dispatching any subagent:**

- Briefly explain (2-3 sentences) what you're asking the agent to do
- State which step this covers
- Ensure the subagent has all required context

**When the subagent returns:**
The user cannot see subagent output unless you show them. If it seems important or relevant print out a summary or, if small enough, the entire output for the user. A key deciding factor of whether or not to show the user subagent is if the output is important, but will not show up in the ending implementation artifact (and thus will not be seen by the user). Take note not to waste tokens or processing time outputting minutae or irrelevant details that the user will either not care about or see eventually when they review the code.

## REQUIRED: Implementation Plan Path

**DO NOT GUESS.** If the user has not provided a path to an implementation plan, you MUST ask for it.

Use AskUserQuestion:

```
Question: "Which implementation plan should I execute?"
Options:
  - [list the newest plan files you find in docs/plans/]
  - "Let me provide the path"
```

If `docs/plans/` doesn't exist or is empty, ask the user to provide the path directly.

**Never assume, infer, or guess which plan to execute.** The user must explicitly tell you.

## The Process

### 1. Create Phase-Level Task List

Think deeply about what's being asked of you. The final result of this implementation should be SIMPLE, CLEAN, and ELEGANT. Code should be easy to read, very maintainable, easily testable, and deeply thought through. Code should never be written for the sake of writing it, every LoC should have a strong purpose. Always bias towards refactoring or removing code before implementing net new. Do not implement one off solutions, make things as general as reasonable. If you do need to implement net new code think in terms of building blocks instead of purpose specific, tightly coupled glue code. Implement for the future as well as right now, never code yourself into a corner, ensure code architecture is extensible and flexible, and do your best to leave the codebase better than how you found it.

**MANDATORY:** Your implementation taks list should be optimally ordered so that not only are the steps logical and increasing in complexity, first creating foundational building blocks or required underlying logic, but also so that context is managed as effeciently as possible. If there is a step you can do independently, or something you can implement that you will later treat as a black box, order those steps earlier so that they can be summarized or removed from context for later steps.

Use TaskCreate to create **three task entries per step** (or TodoWrite in older Claude Code versions). The first task entry per step should be implementation, the second should be testing and verification, the third should be code review:

```
- [ ] Step 1a: Implement base types
- [ ] Step 1b: Write tests
- [ ] Step 1c: Code review
- [ ] Step 2a: Implement hot path
- [ ] Step 2b: Write tests
- [ ] Step 2c: Code review
...
```

**Why absolute paths in task entries:** After compaction, context may be summarized. The absolute path in the task entry ensures you always know exactly which file to read.

**Why include the title:** Gives visibility into what each phase covers without loading full content.

### 2. Execute

For each step, follow this cycle:

#### 2a. Implement the task

Mark "Step Na: Implementation" as in_progress and dispatch `task-implementer` to begin.

```
<invoke name="Task">
<parameter name="subagent_type">one-shot:task-implementer</parameter>
<parameter name="description">Implementing Step X, Task Y: [description]</parameter>
<parameter name="prompt">

... fleshed out prompt goes here ...

</parameter>
</invoke>
```

#### 2b. Write tests and verify correctness

Mark "Step Nb: Tests and Verification" as in_progress and dispatch `task-implementer` to begin.

```
<invoke name="Task">
<parameter name="subagent_type">one-shot:task-implementer</parameter>
<parameter name="description">Writing tests for Step X, Task Y: [description]</parameter>
<parameter name="prompt">

... fleshed out prompt goes here ...

</parameter>
</invoke>
```

#### 2c. Code Review for Step

Mark "Step Nc: Code review" as in_progress.

**MANDATORY:** Use the `requesting-code-review` skill for the review loop.

**Context to provide:**

- WHAT_WAS_IMPLEMENTED: Summary of all tasks in this phase
- PLAN_OR_REQUIREMENTS: All tasks from this phase
- BASE_SHA: commit before phase started
- HEAD_SHA: current commit

**If code reviewer returns a context limit error:**

The phase changed too much for a single review. Chunk the review:

1. Identify the midpoint of tasks in the phase
2. Run code review for first half of tasks (commits for tasks 1 through N/2)
3. Fix any issues found
4. Run code review for second half of tasks (commits for tasks N/2+1 through N)
5. Fix any issues found

**When issues are found**, dispatch `task-implementer` with the feedback:

```
<invoke name="Task">
<parameter name="subagent_type">one-shot:task-implementer</parameter>
<parameter name="description">Fixing review issues for Step X</parameter>
<parameter name="prompt">
  Fix issues from code review for Step X.

  Original prompt: [implementation step prompt]

  Code reviewer found these issues:
  [list all issues - Critical, Important, and Minor]

  Read the phase file to understand the tasks and context.

  Your job is to:
  1. Understand root cause of each issue
  2. Apply fixes systematically (Critical → Important → Minor)
  3. Verify with tests/build/lint
  4. Commit your fixes
  5. Report back with evidence

  Fix ALL issues — including every Minor issue. The goal is ZERO issues on re-review.
  Minor issues are not optional. Do not skip them.
</parameter>
</invoke>
```

After task-implementer completes the fixes, re-review per the `requesting-code-review` skill. Continue loop until zero issues.

**Plan execution policy (stricter than general code review):**

- ALL issues must be fixed (Critical, Important, AND Minor)
- Ignore APPROVED/BLOCKED status - count issues only
- **Three-strike rule:** If same issues persist after three review cycles, stop and report the issue

**Minor issues are NOT optional.** Do not rationalize skipping them with "they're just style issues" or "we can fix those later." The reviewer flagged them for a reason. Fix every single one.

**Exit condition:** Zero issues in all categories — including Minor.

Mark "Step Nc: Code review" as complete.

**MANDATORY:** After finishing the code review section of each task intelligently compact your context. The goal here is to constantly prune context overtime, not neccessarily completely rebuild it. **NOT PRUNING ANY CONTEXT IS A FAILURE THAT SHOULD BE REPORTED TO THE USER**. Even if you prune 5% of context, that is desireable. Since you are an advanced LLM you should have some idea of what you have left to do in this session, use that intelligence to understand what is neccessary in your context for the future and what isn't.

Common Thought Patterns When Smart Compacting - **STOP**

| Do