Skip to content
Development
Skill

/backlog

Capture an out-of-scope improvement or accepted simplification in .turbo/backlog.md. Use proactively mid-task, or when the user asks to \"backlog this\", \"note this idea\", or \"track this for later\".

From plugin
turbo
42074 skills

Claude Code

$ npx -y skills add tobihagemann/turbo --skill backlog --agent claude-code

SKILL.md

backlog.SKILL.md
name: backlog
description: "Capture an out-of-scope improvement or accepted simplification in .turbo/backlog.md. Use proactively mid-task, or when the user asks to \"backlog this\", \"note this idea\", or \"track this for later\"."

Backlog

Capture improvement opportunities discovered during work so they don't get silently dropped. Appends to the `.turbo/backlog.md` file of the repo an improvement concerns.

Step 1: Locate the Backlog File

Each repo keeps its backlog at `.turbo/backlog.md` relative to that repo's root. Resolve that root with `git -C <repo path> rev-parse --show-toplevel`, except inside a linked worktree — where `git -C <repo path> rev-parse --git-dir` differs from `--git-common-dir` — in which case use the parent of the common dir, so the entry lands in the main checkout rather than in a worktree that is destroyed with its branch.

Step 2: Identify the Improvement

Gather from context or `$ARGUMENTS`:

  • **What**: One-line summary of the improvement
  • **Type**: One of `direct`, `investigate`, or `plan` — see criteria below
  • **Category**: One of `refactor`, `performance`, `reliability`, `readability`, `testing`, `docs`, `dx` (developer experience), or `feature`
  • **Where**: File path(s) and/or area of the codebase affected
  • **Why**: Brief rationale — what's the benefit? For a defect or risk, whether it was observed in use or derived from reading code or a review.
  • **Ceiling** and **Revisit**: when the entry records a deliberate simplification, meaning a simpler approach was shipped in place of a fuller one and accepts a known limit — the limit the shipped approach accepts, and the condition that makes the fuller version worth building. **Revisit** alone when the entry waits on an outside event: that event

Type criteria

  • **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).

When the criteria above clearly select one value, use it. Otherwise, use `AskUserQuestion` to confirm; default to `plan` if the user declines to choose.

Step 3: Route and Append

  • Append the entry to the `.turbo/backlog.md` of the repo whose files its **Where** names, which may not be the current repo.
  • When **Where** spans several repos, split it into one entry per repo and append each to its own repo. Give every entry the titles of all its counterparts so a reader of any one backlog finds the others.
  • Rewrite each split entry's **Where** so its paths read repo-local, matching the entries already in that backlog. Qualify any remaining reference that resolves only in another repo with the repo it lives in.
  • When a target repo's checkout cannot be found on disk, use `AskUserQuestion` to ask where it is cloned, offering as the alternative to note its entry in the backlog of the repo root resolved in Step 1. Given a path, route the entry to the repo at that path. Without one, say that the checkout was not found and append the entry to that backlog, naming the repo it was meant for.
  • Write to any path outside the current working directory with the Edit or Write tool, the main checkout of the worktree this session runs in included. The Bash sandbox denies a shell append there, and a separately-issued verification command then prints the file's unchanged contents, which reads as success.
  • When that write is refused while this session runs inside a linked worktree, report that the entry cannot be persisted from here and print the fully formatted entry so it can be pasted in from a session that can write to the main checkout. Leave it out of the worktree's own `.turbo/`, which is gitignored and is destroyed with the worktree.

When a target repo holds the legacy `.turbo/improvements.md`, carry it into that repo's `.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` in each target repo if it exists. Create it with the header below if it doesn't.

**File header** (only when creating new):

# Backlog

Out-of-scope improvement opportunities captured during work sessions. Review periodically and pull items into active work when appropriate.

**Entry format:**

### <one-line summary>

- **Type**: <direct | investigate | plan>
- **Category**: <category>
- **Where**: `<file path or area>`
- **Why**: <brief rationale>
- **Ceiling**: <limit the shipped approach accepts>
- **Revisit**: <condition that makes the fuller version worth building>
- **Paired with**: <repo> — <title of the counterpart entry>
- **Noted**: <YYYY-MM-DD>

Include the Ceiling and Revisit lines when the entry records a deliberate simplification, the Revisit line alone when the entry waits on an outside event, and a Paired with line per counterpart when the entry is one half of a split; omit them otherwise. Append the new entry at the end of each target file.

Step 4: Confirm

Tell the user the improvement was noted and where each entry was written, or that it could not be persisted and is printed above.

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

Rules

  • Deduplicate before appending: search each target backlog for the paths and symbols the new entry names and for entries on a similar subject, and update an existing entry in place when it covers the same improvement. When the existing entry predates the Type field, add a Type line while u
Read more
@tobihagemann
Ships withturbo

A human-gated agentic software factory for Claude Code and Codex: you decide what to build and judge the result; skills shape, build, polish, ship, and learn.

Stars on GitHub

Momentum

stars in total
420
Star history of tobihagemann/turbo on GitHub, a chart by star-history.com

Other skills on turbo.

apply-turbo-handoffs

apply-turbo-handoffs

Audit the turbo lessons /self-improve wrote to .turbo/handoff/ and apply approved ones. Use when the user asks to \"read…

@tobihagemann@tobihagemannInstall Skill
apply-findings

apply-findings

Apply accepted review findings as code changes, escalating ambiguous ones to the user. Use when the user asks to \"apply…

@tobihagemann@tobihagemannInstall Skill
assess-technical-debt

assess-technical-debt

Assess project-wide technical debt (hotspots, deprecated APIs, duplication, low-value tests) into a ranked report. Use when the…

@tobihagemann@tobihagemannInstall Skill
code-style

code-style

Enforce existence, reuse, mirror, and symmetry principles so new code stays minimal and consistent. Use when writing, changing,…

@tobihagemann@tobihagemannInstall Skill
codex-exec

codex-exec

Run autonomous task execution using the codex CLI. Use when the user asks to \"codex exec\", \"run codex exec\", \"execute a task…

@tobihagemann@tobihagemannInstall Skill

More skills from other plugins.

brainstorming
Auto-invoked

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or…

@obra@obraInstall Skill
ask-matt

ask-matt

Ask which skill or flow fits your situation. A router over the skills in this repo.

skills2w309k
@mattpocock@mattpocockInstall Skill
accessibility
Auto-invoked

accessibility

Design, implement, and audit accessible UI to WCAG 2.2 Level AA across Web, iOS, and Android — semantic ARIA roles and labels,…

ecc2w293k
@affaan-m@affaan-mInstall Skill
compiler-commit

compiler-commit

Use when you want to verify compiler changes and commit with the correct convention. Runs tests, lint, and format, then commits…

react6d252k
@facebook@facebookInstall Skill

Questions about backlog.

Which coding agents can use backlog?
backlog installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.