Skip to content

tobihagemann/turbo / claude/skills/implement-backlog

implement-backlog

Verified

Validate .turbo/backlog.md entries, recommend a working set, and run one lane: direct, investigate, or plan. Use when the user asks to "implement the backlog" or "implement improvements".

Implement Backlog

Validate improvements from .turbo/backlog.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.

When a working set and a lane were passed in, by the user or in a message from another session, start at Step 5 with them and create tasks for Steps 5 and 6 alone. Resolve the repo root as Step 1 does, read each working-set entry in full from .turbo/backlog.md under it, and run the lane with each entry's full text alongside what was passed in. When an entry is not there, run the lane with what was passed in for it.

Task Tracking

At the start, use TaskCreate to create a task for each step:

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

Step 1: Read the Backlog

Resolve the repo root 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.

When that root holds the legacy .turbo/improvements.md, carry it into .turbo/backlog.md before reading, with the Write or Edit tool. When .turbo/backlog.md does not exist, write the legacy content there with its # Improvements header changed to # Backlog. Otherwise, append each legacy entry that .turbo/backlog.md does not already hold word for word. Once .turbo/backlog.md holds every legacy entry, delete the legacy file. When the write or the deletion is refused, tell the user what is left to do.

Read .turbo/backlog.md under that root. If it does not exist, there are no backlog entries 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; Revisit alone when the entry waits on an outside event)
  • Noted (date)
  • Validated (present when an earlier run recorded what the entry's verdict rested on)

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 settle the Type of any entry whose Type is missing or wrong.

Reuse an Earlier Validation

Before validating, note the root of the checkout whose code this step reads (git rev-parse --show-toplevel). When that checkout has the default branch checked out (resolve it with gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'), run git -C <root> fetch and fast-forward that branch to its upstream with git -C <root> merge --ff-only @{upstream}. When any of these commands fails, report it and validate the checkout as it stands. Then note its commit (git -C <root> rev-parse --short HEAD). The path check for a commit and a set of repo-relative paths passes when git -C <root> diff --quiet <commit> -- <paths> exits 0 and git -C <root> ls-files --others --exclude-standard -- <paths> prints nothing.

For each entry carrying a Validated line, run the path check with its recorded commit and paths, and run each command nested under it from that root. When the path check passes and every command prints its recorded output, whatever its exit status, classify the entry with its recorded verdict and skip the rest of this step for it. Otherwise, including when a command cannot run, validate the entry in full.

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. A 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. Before dropping an item on the grounds that an existing check covers it, confirm that the check pins that item through its own inputs or match patterns rather than inferring it from the check's name or description; an item no existing check pins stays in the entry's scope. 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, that a change would alter observable behavior, or that the code as it stands leads to a stated outcome, verify the consequence itself rather than confirming only that the code it points at exists. For a claimed difference, between two paths or between the behavior before and after a change, read what each actually returns, exercising both when reading cannot settle it. For a claimed outcome, follow the path from the named code to that outcome and confirm nothing later on that path already stops it. 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.

Before using a restatement as an entry's summary in Step 3, confirm each fact it adds to the entry against the code, or against the dependency's shipped artifact when the fact concerns a dependency. When the fact is that a dependency provides a capability, also confirm that the dependency's documentation says the capability is available, since code present in the shipped artifact can be gated off, internal, or not yet public.

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, or the event the entry waits on has not happened
  • 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 or Correct the Type

For any Active entry without a Type field, infer one on the fly. For an Active entry whose Type the code read contradicts, correct it. A recorded investigate is contradicted only when the code read settles the question the entry raises. Reading alone does not settle a question that turns on runtime behavior, such as ordering or timing. 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 /plan, which routes the work itself.

Pick the type without asking the user. Default to plan when a missing Type is genuinely ambiguous, and keep a recorded Type the code read does not contradict.

Step 3: Recommend, Confirm, and Update the Backlog

When at least two entries are Active, use the ListAgents tool and note the local sessions it shows before outputting anything in this step.

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:

## Backlog Status

Reused earlier validations: N of M entries carrying a Validated line

### 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

When no entry is Active, skip the recommendation: a Deferred entry is not a candidate.

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.
  • Supersession — When an active entry's work, or the pending next step of an entry that lays out several, would rewrite, replace, or make moot the code other active entries target, that work can outweigh a direct batch on that code. When another working set is recommended or offered as an alternative and still includes entries it supersedes, mark those entries as likely discarded by that work.
  • Impact vs effort — A reliability or correctness entry whose problem was observed in use often outweighs lower-stakes cleanups even when it's a single entry. One derived from reading code or a review earns no such weight, less still when its fix adds machinery or public interface; count an entry whose Why records no observation as derived. Say in the recommendation when the recommended working set includes one.
  • 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 /plan, which routes the work itself.
  • 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.

Then check the active entries outside the recommended working set for parallel sets: working sets an extra session can run at the same time. A parallel set touches no file the recommended working set or another parallel set touches, and no set supersedes another. Name each parallel set with its lane after the alternatives.

Confirm via AskUserQuestion

Use AskUserQuestion to confirm. Combine into the same prompt:

  1. Confirm the recommended working set or pick one of the named alternatives — include only when active entries exist. When parallel sets exist, add an option that runs the recommended working set here and each parallel set in an extra session, naming how many extra sessions that takes, in place of the weakest alternative when the options would exceed four.
  2. Whether to remove stale entries — include only when stale entries exist
  3. Resolution for unclear items — include only when unclear entries exist

Skip the call when no item applies.

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

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

Record the validation on each Active or Deferred entry that Step 2 validated in full, after its Noted line, replacing any Validated line it carries together with the command lines nested under it:

- **Validated**: <YYYY-MM-DD>, <Active | Deferred> at `<commit>`: `<path>`, `<path>`
  - `<command>` → `<output>`
  • Commit — the commit Step 2 noted.
  • Paths — repo-relative, every file or directory whose content the verdict rests on: the ones the entry names, and the callers, tests, and configuration Step 2 read to reach the verdict.
  • Commands — one line for each fact the verdict rests on that the paths do not pin: a repo-wide search that established something is absent, or a fact outside the repo, such as a dependency's latest release or an upstream issue's state. Have each print the one value the verdict turns on, such as a match count or a release tag.

Leave the Validated line off an entry when the path check fails for its commit and paths now, when git -C <root> ls-files --error-unmatch -- <paths> fails because a path is untracked or ignored, or when a fact its verdict rests on has neither a path nor a command that pins it. A Revisit condition only a person can observe, such as a user report, is exempt and needs no command.

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

Step 4: Brief the Extra Sessions

Skip this step unless the user confirmed the parallel option.

Read references/parallel-split.md and follow its phases.

Step 5: 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 6: Prune Working-Set Entries from the Backlog

When this session runs inside a linked worktree (where git rev-parse --git-dir differs from --git-common-dir), use AskUserQuestion to offer two options: leave the worktree and prune from the main checkout, or stay in the worktree. List leaving first and label it (Recommended). While the branch's pull request is open (gh pr view <branch> --json state), list staying first and label it (Recommended) instead.

  • Leave — Leave with the ExitWorktree tool (action: "keep"). When it reports that no worktree session is active, take the Stay path instead. Otherwise:
    1. Resolve the default branch with gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'. Fast-forward the main checkout's local default branch to origin/<default-branch> without switching the branch the main checkout has checked out. When the fast-forward fails, report it and leave that branch as it is.
    2. When the worktree's commits are on origin/<default-branch> (git merge-base --is-ancestor <branch> origin/<default-branch>) or its branch's pull request is merged (gh pr view <branch> --json state,headRefOid), remove the worktree with git worktree remove <path>. When git refuses over files this session copied in from the main checkout, delete those copies and remove it again. Otherwise keep the worktree, without --force.
    3. Delete the branch with git branch -d <branch> when its commits are on origin/<default-branch>, or with git branch -D <branch> when its pull request is merged and the branch's tip is that pull request's headRefOid. Keep it otherwise, or when git refuses.
    4. Report what was kept, then continue with the rest of this step from the main checkout.
  • Stay — List every edit the rest of this step would make to the backlog, and print each entry /backlog could not persist from the worktree, so both can be applied from a session that can write to the main checkout. Skip the rest of this step, then use the TaskList tool and proceed to any remaining task.

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

  • Direct lane — entries whose fixes were applied
  • Investigate lane — entries the applied fixes resolve in full, and entries whose investigation established that no defect exists
  • Plan lane — entries captured in the plan file /plan wrote, and entries whose fixes were applied in this session. Treat planned entries as processed once the plan is written.

Keep any entries the lane re-classified mid-flight (direct → investigate/plan, or investigate → plan), and any entry of which the working set took only one step of several. These stay in the backlog for a future run. Remove the Validated line, with the command lines nested under it, from each working-set entry that stays. Delete the file if no entries remain.

Rewrite in place each kept entry of which the working set took only one step: restate its summary and Where as the steps that remain. When the rewrite changes the summary, update each Paired with line in counterpart entries that names the old title.

Rewrite in place each entry the investigate lane investigated that stays in the backlog: restate its summary and Where as what remains to do, put what the investigation established in its Why (the root cause it confirmed, or the hypotheses it refuted when the cause stayed unresolved), and set the Type the remainder calls for. When the entry waits on an outside event, such as an upstream fix, record that event as its Revisit. When the rewrite changes the summary, update each Paired with line in counterpart entries that names the old title.

When the restated Where names files in another repo, delete the entry in place of rewriting it, drop each Paired with reference to it from its counterpart entries, then run the /backlog skill for the entry as restated, with its Category, Type, Why, and any Ceiling or Revisit.

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.

When this session left its worktree at the start of this step, run the /backlog skill for each entry /backlog could not persist from the worktree.

Then use the TaskList tool and proceed to any remaining task.

Rules

  • .turbo/ is gitignored. Edits to .turbo/backlog.md are local-only and do not need to be staged or committed.
  • Run exactly one lane per session. Leave active entries outside the confirmed working set and the briefed parallel sets in the backlog for a future run.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall