Optimize Approach

Given a change and its intent, decide whether it takes the most optimal approach — and if not, propose or apply a concretely better one.

This skill is the fourth review lens in this repo, distinct from the three that already exist:

This SKILL.md is a thin index. Detailed rules live in rules/*.md and load on demand.

---

Mode Detection

Parse the first non-flag token of $ARGUMENTS (flags such as --deep may appear anywhere).

Flags

Inputs

When a calling agent (pr-reviewer / polish / aw-planner) invokes this skill, it passes:

• intent_summary — 2–3 line intent (the caller's Step 1.3 output).
• diff — the full unified diff under review.
• changed_files — list of {path, patch} entries.
• caller — pr-reviewer | polish | aw-planner (affects framing and whether apply is allowed). For pr-reviewer, also pass review_relation: "self" | "cross" — self uses assertive framing, cross uses question framing.

For plan mode the caller (aw-planner) passes a drafted plan's approach and its Existing Code Survey verdicts instead of a diff — see rules/plan-mode.md for that input shape.

Standalone (/optimize-approach [report|apply]) derives the diff-mode inputs from the current branch diff against origin/main.

Workflow

O1 — Intent capture

Use intent_summary verbatim when supplied. Standalone, derive it from PR title / body / commit messages / branch name. For a multi-file diff, name each distinct approach unit (one cohesive way of solving one sub-goal) — the judgment in O2 runs per unit, not per line.

O2 — Optimality judgment

Score each approach unit against the four axes in rules/optimality-rubric.md: codebase-fit, simplicity, performance, robustness. Reach one verdict per unit: optimal or suboptimal. A unit is suboptimal only when a materially better alternative exists and clears the anti-overlap and materiality bars in the rubric — otherwise it is optimal.

O3 — Quiet early-exit

If every approach unit is optimal, return an empty finding list and stop. Silence on a well-built change is the expected outcome, not a failure — it is the same "quality over quantity" contract the pr-reviewer agent follows. Still run the O5 end-of-run lesson write (a clean run is recurrence evidence for any lesson applied in O0).

O4 — Deep understanding (suboptimal units only)

Before proposing, understand the change completely — never propose a "better way" from a shallow read.

1. Grep the relevant files, callers, and any existing utility or pattern the alternative would reuse.
2. Invoke Skill("holistic-analysis", "refactor") to trace the execution path of the affected unit and generate + compare approaches.
3. Gate the chosen alternative on Skill("confidence", "analysis"). Report: below 85 % analysis_confidence, drop the proposal — a sub-85 % "better way" is not understood well enough to assert as objectively better (rules/report-mode.md). Apply: requires the higher analysis_confidence ≥ 90 % bar as well — never apply an approach change the analysis is unsure about (rules/apply-mode.md).

O5 — Deliver

• report mode → emit the proposal per rules/report-mode.md.
• apply mode → apply the top proposal per rules/apply-mode.md, behind confidence(code) ≥ 90 %, scoped check, and revert-on-failure.

Then run the fast-tier lesson write + promotion check in rules/self-improvement-loop.md.

Required Reading by Phase

Load on demand — do not preload.

Self-Improvement

This skill runs a two-tier self-improvement loop keyed by the optimize-approach-lessons bucket (LoreKit tag loop::optimize-approach-lessons). The fast tier (LoreKit memory.* tools, via the lorekit-memory skill) reads lessons at O0 and writes them at O5 to calibrate the optimal-vs-suboptimal bar and the apply-safety judgment. A lesson reaching seen_count >= 3 becomes promotion-eligible for the slow tier (/create-skill diagnose optimize-approach). In plan mode it also reads the shared codebase-knowledge signal for the plan's files — a known hotspot or invariant sharpens the optimality call — read-only, advisory (see the loop file's cross-bucket read section and ../../../agents/shared/rules/codebase-knowledge.md). Full contract: rules/self-improvement-loop.md.

Core Principles

1. Approach-level only. Judge the shape of the solution, not lines. Line-level cleanups belong to code-quality; failure modes to critical; intent/system-fit to holistic-review.
2. Silence is the default outcome. Most changes are already optimal enough — say nothing rather than manufacture a "better way".
3. Understand before proposing. A proposal requires a holistic trace and a confidence(analysis) gate — never a shallow "you could also…".
4. Apply only behind the gate. An approach rewrite is applied only at confidence(code) ≥ 90 %, scoped to the diff's files, with revert-on-failure. Otherwise it is proposed, not applied.
5. Never block the verdict. An optimality proposal is advisory (suggestion / question), like scope-creep — it never drives "Request changes".

Anti-patterns (one-liners — full list in the rules)

• Proposing a "better way" that just restates a code-quality mechanical refactor.
• Manufacturing a suboptimal verdict on a change that clears the materiality bar.
• Applying an approach change across files outside the diff, or without the confidence gate.
• Emitting more than the cap of proposals — approach review is quality-over-quantity.
• Blocking the review verdict on an optimality finding.

Definition of Done

• Verdict reached per approach unit (optimal → empty; suboptimal → proposal).
• Every suboptimal proposal carries a holistic trace and a confidence(analysis) score.
• apply mode gated on confidence(code) ≥ 90 % + scoped check + revert-on-failure.
• Fast-tier lesson write + promotion check ran at O5.