agentic-tools

Chase a measured improvement goal against a benchmark or evaluation, raising a primary metric without regressing guard metrics. Use when the task is to improve something an on-demand evaluation can measure (benchmark scores, quality evals, latency or cost budgets). Do not use when no runnable evaluation exists (building one is then the first deliverable), for behavior-preserving restructuring (refactor), or for diagnosing failures (take-a-step-back).

Diagnose and redesign work that is stuck, repeatedly failing, expensive, drifting, or accumulating abstractions without a current consumer. Use when the user asks to step back; patches or runs are not converging; debugger, benchmark, or model-heavy work needs stop-loss; progress is unclear; or a proposed support layer may be unnecessary.

Restructure code without changing behavior. Covers readability work, extractions, moves, and de-duplication where the contract is that existing behavior is preserved. Use when the task is refactor-shaped or the user asks for cleanup or restructuring. Do not use for changes meant to alter behavior (that is implementation under the design docs) or for diagnosing failures (take-a-step-back).

Run the harness retro, turning accumulated task receipts into instruction changes and reviewing the previous retro's changes against evidence to keep, amend, or revert them. Use when scripts/receipt.sh check reports a retro due or the human asks for one. Do not use for code changes (normal work) or for mid-task rule additions (forbidden by the contract).

Prove a code change works by driving the changed behavior end-to-end and observing the result instead of inferring it from green checks. Use before calling any change with a runnable surface complete. Do not use for changes with no runtime surface (docs, comments, pure test edits) or as a substitute for focused unit tests.

Diagnose live Java runtime behavior through JDWP and debugger tools. Use for runtime bugs, wrong branches or state, concurrency/deadlocks, variable or thread inspection, breakpoints and stepping, timeout attribution, or proving an end-to-end causal chain. Do not use when static code/tests already prove the cause or when the task only asks to implement a known fix.