Note Improvement
Capture improvement opportunities discovered during work so they don't get silently dropped. Appends to the .turbo/improvements.md backlog of the repo an improvement concerns.
Step 1: Locate the Improvements File
Each repo keeps its improvements file at .turbo/improvements.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?
- 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
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 request_user_input to confirm; default to plan if the user declines to choose.
Step 3: Route and Append
- Append the entry to the
.turbo/improvements.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 is absent from disk, say so plainly and append its entry to the backlog of the repo root resolved in Step 1, naming the repo it was meant for.
Read .turbo/improvements.md in each target repo if it exists. Create it with the header below if it doesn't.
File header (only when creating new):
# Improvements
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, 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.
Rules
- Deduplicate before appending: check each target backlog for a similar entry and update it in place when one exists. When the existing entry predates the Type field, add a Type line while updating.
- When updating an existing entry tagged with the legacy values
trivial or standard, rewrite the Type to direct or plan respectively so the file converges on current vocabulary.
- Keep entries concise. These are backlog items, not specs.
- When a deliberate simplification's revisit condition is not yet knowable, record what would have to be observed to know it.
- Record only; leave action to the user, who decides when to address it.
- When a target repo has no
.turbo/ directory, use request_user_input to confirm the location before creating one.
1---2name: note-improvement-33description: Capture an out-of-scope improvement opportunity so it doesn't get lost. Use when the user asks to "note improvement", "save improvement", "track this for later", "remember this improvement", "note this idea", "log improvement", "backlog this", or "park this idea". Also invoke proactively when noticing something improvable during work that falls outside the current task's scope, or after deliberately shipping a simpler approach that accepts a known ceiling — briefly mention it to the user and offer to note it.4---56# Note Improvement78Capture improvement opportunities discovered during work so they don't get silently dropped. Appends to the `.turbo/improvements.md` backlog of the repo an improvement concerns.910## Step 1: Locate the Improvements File1112Each repo keeps its improvements file at `.turbo/improvements.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.1314## Step 2: Identify the Improvement1516Gather from context or `$ARGUMENTS`:1718- **What**: One-line summary of the improvement19- **Type**: One of `direct`, `investigate`, or `plan` — see criteria below20- **Category**: One of `refactor`, `performance`, `reliability`, `readability`, `testing`, `docs`, `dx` (developer experience), or `feature`21- **Where**: File path(s) and/or area of the codebase affected22- **Why**: Brief rationale — what's the benefit?23- **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 building2425### Type criteria2627- **direct** — Clear scope and a known approach, ready to apply via `$implement`.28- **investigate** — A symptom that needs root-cause analysis first: unclear root cause, performance question, intermittent bug, "something feels off".29- **plan** — Everything else: the approach warrants writing down before implementing (multi-file refactor, test additions, feature work).3031When the criteria above clearly select one value, use it. Otherwise, use `request_user_input` to confirm; default to `plan` if the user declines to choose.3233## Step 3: Route and Append3435- Append the entry to the `.turbo/improvements.md` of the repo whose files its **Where** names, which may not be the current repo.36- 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.37- 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.38- When a target repo is absent from disk, say so plainly and append its entry to the backlog of the repo root resolved in Step 1, naming the repo it was meant for.3940Read `.turbo/improvements.md` in each target repo if it exists. Create it with the header below if it doesn't.4142**File header** (only when creating new):4344```markdown45# Improvements4647Out-of-scope improvement opportunities captured during work sessions. Review periodically and pull items into active work when appropriate.48```4950**Entry format:**5152```markdown53### <one-line summary>5455- **Type**: <direct | investigate | plan>56- **Category**: <category>57- **Where**: `<file path or area>`58- **Why**: <brief rationale>59- **Ceiling**: <limit the shipped approach accepts>60- **Revisit**: <condition that makes the fuller version worth building>61- **Paired with**: <repo> — <title of the counterpart entry>62- **Noted**: <YYYY-MM-DD>63```6465Include the Ceiling and Revisit lines when the entry records a deliberate simplification, 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.6667## Step 4: Confirm6869Tell the user the improvement was noted and where each entry was written.7071## Rules7273- Deduplicate before appending: check each target backlog for a similar entry and update it in place when one exists. When the existing entry predates the Type field, add a Type line while updating.74- When updating an existing entry tagged with the legacy values `trivial` or `standard`, rewrite the Type to `direct` or `plan` respectively so the file converges on current vocabulary.75- Keep entries concise. These are backlog items, not specs.76- When a deliberate simplification's revisit condition is not yet knowable, record what would have to be observed to know it.77- Record only; leave action to the user, who decides when to address it.78- When a target repo has no `.turbo/` directory, use `request_user_input` to confirm the location before creating one.
tobihagemann