note-improvement

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 AskUserQuestion 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.
• 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.