Claude Skill

implement-improvements

Validate improvements from .turbo/improvements.md, recommend a working set tailored to what's in the backlog, and run one lane: direct fixes, investigation, or planned work. One lane per session. Use when the user asks to "implement improvements", "work on improvements", "address

LLM Mart · 0 points · 17 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download tobihagemann-turbo-codex_skills_implement-improvements-49d2402.zip · 6 KB
tobihagemann/turbo 403 31 forks MIT Updated 1d ago
Part of tobihagemann/turbo — 147 skills

Install

skills CLI npx skills add https://github.com/tobihagemann/turbo/tree/main/codex/skills/implement-improvements
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tobihagemann-turbo@llmmart
Git git clone https://github.com/tobihagemann/turbo.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole tobihagemann/turbo collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Implement Improvements

Validate improvements from .turbo/improvements.md, propose a specific working set based on the backlog's actual contents, and run one lane per session: direct, investigate, or plan. Mixing lanes in a single run tangles commits, so the skill processes exactly one lane each time. Entries outside the confirmed working set stay in the backlog for future runs.

Task Tracking

At the start, use update_plan to track each step, restating any remaining steps of a parent workflow alongside them:

  1. Read the backlog
  2. Validate and classify
  3. Recommend, confirm, and update the backlog
  4. Run the chosen lane
  5. Prune working-set entries from the backlog

Step 1: Read the Backlog

Read .turbo/improvements.md, relative to the repo root resolved with git rev-parse --show-toplevel, except inside a linked worktree — where git rev-parse --git-dir differs from --git-common-dir — in which case use the parent of the common dir. If the file does not exist, there are no improvements to implement; stop.

Parse all entries, extracting for each:

  • Summary (the ### heading)
  • Type (direct, investigate, or plan; may be missing in older entries — trivial and standard are accepted as legacy aliases for direct and plan)
  • Category
  • Where (file paths or areas)
  • Why (rationale)
  • Ceiling and Revisit (present when the entry records a deliberate simplification)
  • Noted (date)

Step 2: Validate and Classify

Improvements drift: files get renamed, code gets refactored, issues get fixed as side effects of other work. Before routing, validate each improvement and classify any entry missing a Type.

Validate

For each entry, verify whether the specific problem or opportunity described still exists. Do not rely on git log alone. Recent commits touching the same files do not mean the specific issue was addressed. Read the actual code and confirm:

  1. Files exist — Do the referenced files/paths still exist? When one was renamed or its code moved, validate the entry at the current location instead. This check marks the entry stale only when the code it names is gone.
  2. Problem persists — Read the relevant code sections. Is the exact issue or opportunity described in the entry still present? Check the specific claims: if the entry says a function is uncalled, verify it has no callers; if it says error handling is missing, check whether it was added.
  3. Revisit condition met — For an entry carrying a Revisit field, check whether the recorded condition now holds. The shipped simplification is present by construction, so its presence alone says nothing about whether the fuller version is worth building yet.
  4. Stated scope matches the real gap — For an entry claiming missing coverage, read what existing tests already pin before accepting its scope: a test that substitutes a test double at a boundary pins the behavior on one side of it and leaves the boundary itself unpinned, so a request to cover several variants often reduces to the single boundary they share. Restate such an entry at its real scope, classify it Active, and use the restatement as its summary in Step 3.
  5. Claimed consequence holds — For an entry claiming that two paths behave differently, or that a change would alter observable behavior, verify the claimed difference itself by reading what each path actually returns, exercising both when reading cannot settle it, rather than confirming only that the code it points at exists. When the claim is that nothing but the case it names reaches or relies on the named code, read that code's own tests: they surface dependents an entry written from a single path routinely omits, and turning up none leaves the claim unproven. When the named code is present but its stated consequence is false, restate the entry at the benefit it actually delivers, classify it Active, and use the restatement as its summary in Step 3; classify it Stale when no benefit survives.

Classify each entry as:

  • Active — The described problem or opportunity is confirmed present in the current code
  • Deferred — The entry carries a Revisit condition that does not yet hold; the shipped approach remains the right one
  • Stale — The code the entry names no longer exists, the specific issue has been resolved, or the entry's premise never held (cite evidence: what changed and where, or why the claim is false)
  • Unclear — Cannot determine from code alone, needs user input

When in doubt, classify as Active. The cost of re-examining a resolved issue is low; dismissing a valid improvement is high.

Classify type if missing

For any Active entry without a Type field, infer one on the fly. Base the classification on the code you just read during validation, not just the entry's one-line summary.

  • direct — Clear scope and a known approach, ready to apply via $implement.
  • investigate — A symptom that needs root-cause analysis first: unclear root cause, performance question, intermittent bug, "something feels off".
  • plan — Everything else: the approach warrants writing down before implementing (multi-file refactor, test additions, feature work). Dispatched to $turboplan, which routes the work itself.

Pick the type without asking the user. Default to plan when genuinely ambiguous.

Step 3: Recommend, Confirm, and Update the Backlog

Output the backlog status as text first, grouped by type and status. Include each entry's category inline and a category tally across active entries:

## Improvement Backlog Status

### Active (N)
Categories: refactor (N), performance (N), testing (N), docs (N)

**Direct (N)**
- [summary] (category) — [one-line reason it's still relevant]

**Investigate (N)**
- [summary] (category) — [one-line reason it's still relevant]

**Plan (N)**
- [summary] (category) — [one-line reason it's still relevant]

### Deferred (N)
- [summary] — [the revisit condition, and what still has to happen]

### Stale (N)
- [summary] — [one-line reason it's stale]

### Unclear (N)
- [summary] — [what's ambiguous]

Recommend a Working Set

Pick one specific working set tailored to the active entries. Read the entries again before recommending and weigh:

  • Cohesion — Entries that share files, modules, or themes are stronger when batched. A cluster of related testing or reliability entries usually beats a scattered mix.
  • Decisiveness — One investigation that unblocks several deferred entries can outweigh a larger direct batch.
  • Impact vs effort — A reliability or correctness entry often outweighs lower-stakes cleanups even when it's a single entry.
  • Lane shape — Each lane batches a cluster, just in different shapes. Direct groups clear-scope fixes into one $implement run. Investigate dispatches $investigate per symptom, then shares one $implement for the concluded fixes. Plan hands a cohesive cluster to $turboplan, which routes it to a plan file.
  • Unit of work size — Right-size the session. Prefer the whole cohesive cluster over a narrow filter unless the filter clearly preserves a coherent unit of work; picking 1–2 entries off a cluster of 7 wastes the slot. Route any entry that turns out to be a clear-scope direct fix to the direct lane instead.
  • Backlog state — Heavy direct concentration calls for clearing the cluster; a long-deferred symptom often deserves the slot.

State the recommendation as: lane + concrete working set (specific entries or a category-scoped subset) + one or two sentences on why this beats the alternatives. Then list 1–3 honest alternatives, each named with the actual entry or subset (e.g., "investigate the flaky presence test", "plan lane on persist-before-send"). When only one lane has active entries, recommend that lane and skip alternatives.

Confirm with the User

Use request_user_input to confirm. Combine into the same prompt:

  1. Confirm the recommended working set or pick one of the named alternatives
  2. Whether to remove stale entries — include only when stale entries exist
  3. Resolution for unclear items — include only when unclear entries exist

If the user confirmed stale removal, edit .turbo/improvements.md to delete the stale entries.

Rewrite in .turbo/improvements.md each Active or Deferred entry whose path, scope, count, or consequence Step 2 corrected, changing only the fields the correction touches. When that changes an entry's summary, update each Paired with line in its counterpart entries that names the old title.

Compute the working set from the confirmed choice. If the working set is empty, stop.

Step 4: Run the Chosen Lane

Read the reference file for the confirmed lane and follow its phases:

State the chosen lane before continuing with the reference file.

Step 5: Prune Working-Set Entries from the Backlog

Edit .turbo/improvements.md to delete the working-set entries that the lane processed. "Processed" means:

  • Direct lane — entries whose fixes were applied
  • Investigate lane — entries whose concluded fixes were applied
  • Plan lane — entries now captured in the plan produced by $turboplan; treat them as processed once the plan is written.

Keep any entries the lane re-classified mid-flight (direct → investigate/plan, or investigate → plan). These stay in the backlog for a future run. Delete the file if no entries remain.

When a processed entry carries a Paired with line, drop that reference from each counterpart entry it names, so no backlog is left pointing at an entry that no longer exists.

Rules

  • .turbo/ is gitignored. Edits to .turbo/improvements.md are local-only and do not need to be staged or committed.
  • Run exactly one lane per session. Leave other active entries in the backlog for a future run.
Files (turbo)
  • references
    • direct-lane.md 749 B 
      # Implement Improvements: Direct Lane

Apply the working-set fixes directly via `$implement`.

The working set is the entries the user confirmed in SKILL.md Step 3.

## Task Tracking

Use `update_plan` to track each phase:

1. Run `$implement` skill

## Phase 1: Run `$implement` Skill

In the turn that invokes `$implement`, write out each fix in the working set as an explicit bullet: summary + files + change description. If an entry turns out to need broader scope or deeper analysis during implementation, stop and re-classify it as `investigate` or `plan` (leave it in the backlog for a future run).

Then run the `$implement` skill.

Then call `update_plan` to mark this step completed and continue with the next step of the active workflow.
    • investigate-lane.md 1.8 KB 
      # Implement Improvements: Investigate Lane

Diagnose each working-set entry via `$investigate`, then apply the concluded fixes via `$implement`.

The working set is the entries the user confirmed in SKILL.md Step 3.

## Task Tracking

Track each phase with the Codex plan tool:

1. Run `$investigate` skill for each working-set entry
2. Run `$implement` skill for the concluded fixes

## Phase 1: Run `$investigate` Skill for Each Working-Set Entry

Before starting the loop, add one sub-task per entry in the working set (e.g., `Investigate: <summary>`). Mark each sub-task `in_progress` before the corresponding `$investigate` run and `completed` after.

For each entry in the working set, run the `$investigate` skill. In the problem statement passed to `$investigate`, include the entry's summary and rationale, then append a note that this is an improvement-backlog entry likely to be a symptom and that `$investigate` must run `$consult-claude` regardless of how many hypotheses surface.

If `$investigate` surfaces complexity that exceeds a single-session fix (multi-subsystem change, architectural decision), stop that entry and re-classify it as `plan` (leave it in the backlog for a future run).

## Phase 2: Run `$implement` Skill for the Concluded Fixes

In the turn that invokes `$implement`, write out each investigation's concluded fix as an explicit bullet: summary + files + change description. Being explicit matters here because `$investigate`'s earlier output has likely displaced continuation context, so `$implement` needs a fresh, self-contained description.

Then run the `$implement` skill.

Then call `update_plan` to mark this step completed and continue with the next step of the active workflow.

## Rules

- Run the close-out only once (inside `$implement` in Phase 2), not once per investigation.
    • plan-lane.md 757 B 
      # Implement Improvements: Plan Lane

Run `$turboplan` with the working-set entries. The user runs `$implement-plan` in a fresh session afterward.

The working set is the entries the user confirmed in SKILL.md Step 3.

## Task Tracking

Use `update_plan` to track each phase:

1. Run `$turboplan` skill

## Phase 1: Run `$turboplan` Skill

Run the `$turboplan` skill with the working set as the task description. Include planning constraints:

- **Synergies** — Group improvements that touch the same files or areas
- **Dependencies** — Order so foundational changes come first
- **Conflicts** — Flag if two improvements contradict each other

Then call `update_plan` to mark this step completed and continue with the next step of the active workflow.
  • SKILL.md 10.3 KB 
    ---
name: implement-improvements
description: "Validate improvements from .turbo/improvements.md, recommend a working set tailored to what's in the backlog, and run one lane: direct fixes, investigation, or planned work. One lane per session. Use when the user asks to \"implement improvements\", \"work on improvements\", \"address improvements\", \"process improvement backlog\", \"tackle improvements\", or \"implement noted improvements\"."
---

# Implement Improvements

Validate improvements from `.turbo/improvements.md`, propose a specific working set based on the backlog's actual contents, and run one lane per session: direct, investigate, or plan. Mixing lanes in a single run tangles commits, so the skill processes exactly one lane each time. Entries outside the confirmed working set stay in the backlog for future runs.

## Task Tracking

At the start, use `update_plan` to track each step, restating any remaining steps of a parent workflow alongside them:

1. Read the backlog
2. Validate and classify
3. Recommend, confirm, and update the backlog
4. Run the chosen lane
5. Prune working-set entries from the backlog

## Step 1: Read the Backlog

Read `.turbo/improvements.md`, relative to the repo root resolved with `git rev-parse --show-toplevel`, except inside a linked worktree — where `git rev-parse --git-dir` differs from `--git-common-dir` — in which case use the parent of the common dir. If the file does not exist, there are no improvements to implement; stop.

Parse all entries, extracting for each:

- **Summary** (the `###` heading)
- **Type** (`direct`, `investigate`, or `plan`; may be missing in older entries — `trivial` and `standard` are accepted as legacy aliases for `direct` and `plan`)
- **Category**
- **Where** (file paths or areas)
- **Why** (rationale)
- **Ceiling** and **Revisit** (present when the entry records a deliberate simplification)
- **Noted** (date)

## Step 2: Validate and Classify

Improvements drift: files get renamed, code gets refactored, issues get fixed as side effects of other work. Before routing, validate each improvement and classify any entry missing a Type.

### Validate

For each entry, verify whether the specific problem or opportunity described still exists. Do not rely on git log alone. Recent commits touching the same files do not mean the specific issue was addressed. Read the actual code and confirm:

1. **Files exist** — Do the referenced files/paths still exist? When one was renamed or its code moved, validate the entry at the current location instead. This check marks the entry stale only when the code it names is gone.
2. **Problem persists** — Read the relevant code sections. Is the exact issue or opportunity described in the entry still present? Check the specific claims: if the entry says a function is uncalled, verify it has no callers; if it says error handling is missing, check whether it was added.
3. **Revisit condition met** — For an entry carrying a Revisit field, check whether the recorded condition now holds. The shipped simplification is present by construction, so its presence alone says nothing about whether the fuller version is worth building yet.
4. **Stated scope matches the real gap** — For an entry claiming missing coverage, read what existing tests already pin before accepting its scope: a test that substitutes a test double at a boundary pins the behavior on one side of it and leaves the boundary itself unpinned, so a request to cover several variants often reduces to the single boundary they share. Restate such an entry at its real scope, classify it Active, and use the restatement as its summary in Step 3.
5. **Claimed consequence holds** — For an entry claiming that two paths behave differently, or that a change would alter observable behavior, verify the claimed difference itself by reading what each path actually returns, exercising both when reading cannot settle it, rather than confirming only that the code it points at exists. When the claim is that nothing but the case it names reaches or relies on the named code, read that code's own tests: they surface dependents an entry written from a single path routinely omits, and turning up none leaves the claim unproven. When the named code is present but its stated consequence is false, restate the entry at the benefit it actually delivers, classify it Active, and use the restatement as its summary in Step 3; classify it Stale when no benefit survives.

Classify each entry as:

- **Active** — The described problem or opportunity is confirmed present in the current code
- **Deferred** — The entry carries a Revisit condition that does not yet hold; the shipped approach remains the right one
- **Stale** — The code the entry names no longer exists, the specific issue has been resolved, or the entry's premise never held (cite evidence: what changed and where, or why the claim is false)
- **Unclear** — Cannot determine from code alone, needs user input

When in doubt, classify as Active. The cost of re-examining a resolved issue is low; dismissing a valid improvement is high.

### Classify type if missing

For any Active entry without a Type field, infer one on the fly. Base the classification on the code you just read during validation, not just the entry's one-line summary.

- **direct** — Clear scope and a known approach, ready to apply via `$implement`.
- **investigate** — A symptom that needs root-cause analysis first: unclear root cause, performance question, intermittent bug, "something feels off".
- **plan** — Everything else: the approach warrants writing down before implementing (multi-file refactor, test additions, feature work). Dispatched to `$turboplan`, which routes the work itself.

Pick the type without asking the user. Default to `plan` when genuinely ambiguous.

## Step 3: Recommend, Confirm, and Update the Backlog

Output the backlog status as text first, grouped by type and status. Include each entry's category inline and a category tally across active entries:

```
## Improvement Backlog Status

### Active (N)
Categories: refactor (N), performance (N), testing (N), docs (N)

**Direct (N)**
- [summary] (category) — [one-line reason it's still relevant]

**Investigate (N)**
- [summary] (category) — [one-line reason it's still relevant]

**Plan (N)**
- [summary] (category) — [one-line reason it's still relevant]

### Deferred (N)
- [summary] — [the revisit condition, and what still has to happen]

### Stale (N)
- [summary] — [one-line reason it's stale]

### Unclear (N)
- [summary] — [what's ambiguous]
```

### Recommend a Working Set

Pick one specific working set tailored to the active entries. Read the entries again before recommending and weigh:

- **Cohesion** — Entries that share files, modules, or themes are stronger when batched. A cluster of related testing or reliability entries usually beats a scattered mix.
- **Decisiveness** — One investigation that unblocks several deferred entries can outweigh a larger direct batch.
- **Impact vs effort** — A reliability or correctness entry often outweighs lower-stakes cleanups even when it's a single entry.
- **Lane shape** — Each lane batches a cluster, just in different shapes. Direct groups clear-scope fixes into one `$implement` run. Investigate dispatches `$investigate` per symptom, then shares one `$implement` for the concluded fixes. Plan hands a cohesive cluster to `$turboplan`, which routes it to a plan file.
- **Unit of work size** — Right-size the session. Prefer the whole cohesive cluster over a narrow filter unless the filter clearly preserves a coherent unit of work; picking 1–2 entries off a cluster of 7 wastes the slot. Route any entry that turns out to be a clear-scope direct fix to the direct lane instead.
- **Backlog state** — Heavy direct concentration calls for clearing the cluster; a long-deferred symptom often deserves the slot.

State the recommendation as: lane + concrete working set (specific entries or a category-scoped subset) + one or two sentences on why this beats the alternatives. Then list 1–3 honest alternatives, each named with the actual entry or subset (e.g., "investigate the flaky presence test", "plan lane on persist-before-send"). When only one lane has active entries, recommend that lane and skip alternatives.

### Confirm with the User

Use `request_user_input` to confirm. Combine into the same prompt:

1. Confirm the recommended working set or pick one of the named alternatives
2. Whether to remove stale entries — include only when stale entries exist
3. Resolution for unclear items — include only when unclear entries exist

If the user confirmed stale removal, edit `.turbo/improvements.md` to delete the stale entries.

Rewrite in `.turbo/improvements.md` each Active or Deferred entry whose path, scope, count, or consequence Step 2 corrected, changing only the fields the correction touches. When that changes an entry's summary, update each **Paired with** line in its counterpart entries that names the old title.

Compute the **working set** from the confirmed choice. If the working set is empty, stop.

## Step 4: Run the Chosen Lane

Read the reference file for the confirmed lane and follow its phases:

- **Direct lane** — [references/direct-lane.md](references/direct-lane.md)
- **Investigate lane** — [references/investigate-lane.md](references/investigate-lane.md)
- **Plan lane** — [references/plan-lane.md](references/plan-lane.md)

State the chosen lane before continuing with the reference file.

## Step 5: Prune Working-Set Entries from the Backlog

Edit `.turbo/improvements.md` to delete the working-set entries that the lane processed. "Processed" means:

- **Direct lane** — entries whose fixes were applied
- **Investigate lane** — entries whose concluded fixes were applied
- **Plan lane** — entries now captured in the plan produced by `$turboplan`; treat them as processed once the plan is written.

Keep any entries the lane re-classified mid-flight (direct → investigate/plan, or investigate → plan). These stay in the backlog for a future run. Delete the file if no entries remain.

When a processed entry carries a **Paired with** line, drop that reference from each counterpart entry it names, so no backlog is left pointing at an entry that no longer exists.

## Rules

- `.turbo/` is gitignored. Edits to `.turbo/improvements.md` are local-only and do not need to be staged or committed.
- Run exactly one lane per session. Leave other active entries in the backlog for a future run.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude