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