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:
| Lens |
Question |
Applies? |
holistic-analysis review |
Does the diff do what it claims and fit the system? |
No |
critical |
How could this fail? |
No |
code-quality simplify |
Can this be mechanically simpler? |
Yes — Class M only |
optimize-approach (this skill) |
Is this the most optimal approach, and if not what is? |
Yes — gated |
This SKILL.md is a thin index. Detailed rules live in rules/*.md and load on demand.
Mode Detection
Parse the first token of $ARGUMENTS.
| Mode |
Default |
Trigger |
What it does |
report |
yes |
No mode token, or report |
Emit a structured proposal (or nothing when optimal). Never edits files. |
apply |
|
First token apply |
Same analysis, then apply the top proposal behind a confidence gate. Own-work contexts only. |
plan |
|
First token plan |
Review a drafted plan's approach at plan time (aw-planner Phase 1). Returns plan-level proposals; the planner revises the plan. See rules/plan-mode.md. |
Flags
| Flag |
Applies to |
Effect |
--no-confidence-gate |
apply |
Human-only override. Bypasses the confidence(code) ≥ 90 % gate for a single apply run. Reserved for explicit human slash invocations — a calling agent (pr-reviewer, polish, aw-planner) never sets it. The other apply-mode guards are not waived: apply_safe, the forbidden-targets list, the scoped check, and revert-on-failure all still apply. See rules/apply-mode.md. |
Inputs
When a calling agent (reviewer / pr-reviewer / polish) 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.
- Grep the relevant files, callers, and any existing utility or pattern the alternative would reuse.
- Invoke
Skill("holistic-analysis", "refactor") to trace the execution path of the affected unit and generate + compare approaches.
- 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
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
- 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.
- Silence is the default outcome. Most changes are already optimal enough — say nothing rather than manufacture a "better way".
- Understand before proposing. A proposal requires a holistic trace and a
confidence(analysis) gate — never a shallow "you could also…".
- 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.
- 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
1---2name: optimize-approach3description: Reviews whether a change takes the most optimal approach for its stated intent and, when it does not, researches the code, validates a concretely better approach via holistic analysis, and either proposes it (report mode) or applies it behind a confidence gate (apply mode). Judges four axes — codebase-fit, simplicity, performance, robustness — at the approach level, deferring line-level and failure-mode findings to code-quality, critical, and holistic-review. Stays silent when the approach is already optimal (quiet early-exit). A `plan` mode reviews a drafted plan's approach at plan time (aw-planner Phase 1) — the cheapest moment to switch. Called by the reviewer and pr-reviewer agents, the polish skill, and aw-planner as a default-on lens; also runnable standalone. Triggers on "is this the best approach", "better way to do this", "is this optimal", "optimize this approach", "rethink the approach", "/optimize-approach".4license: MIT5---67# Optimize Approach89Given a change and its intent, decide whether it takes the **most optimal approach** — and if not, propose or apply a concretely better one.1011This skill is the fourth review lens in this repo, distinct from the three that already exist:1213| Lens | Question | Applies? |14| --- | --- | --- |15| `holistic-analysis` review | Does the diff *do what it claims* and *fit the system*? | No |16| `critical` | How could this *fail*? | No |17| `code-quality` simplify | Can this be *mechanically* simpler? | Yes — Class M only |18| **`optimize-approach`** *(this skill)* | Is this the *most optimal approach*, and if not what is? | Yes — gated |1920> **This `SKILL.md` is a thin index.** Detailed rules live in `rules/*.md` and load on demand.2122---2324## Mode Detection2526Parse the **first token** of `$ARGUMENTS`.2728| Mode | Default | Trigger | What it does |29| --- | --- | --- | --- |30| `report` | **yes** | No mode token, or `report` | Emit a structured proposal (or nothing when optimal). Never edits files. |31| `apply` | | First token `apply` | Same analysis, then apply the top proposal behind a confidence gate. Own-work contexts only. |32| `plan` | | First token `plan` | Review a drafted plan's approach at plan time (aw-planner Phase 1). Returns plan-level proposals; the planner revises the plan. See [`rules/plan-mode.md`](./rules/plan-mode.md). |3334## Flags3536| Flag | Applies to | Effect |37| --- | --- | --- |38| `--no-confidence-gate` | `apply` | **Human-only override.** Bypasses the `confidence(code) ≥ 90 %` gate for a single `apply` run. Reserved for explicit human slash invocations — a calling agent (`pr-reviewer`, `polish`, `aw-planner`) **never** sets it. The other apply-mode guards are **not** waived: `apply_safe`, the forbidden-targets list, the scoped check, and revert-on-failure all still apply. See [`rules/apply-mode.md`](./rules/apply-mode.md). |3940## Inputs4142When a calling agent (reviewer / pr-reviewer / polish) invokes this skill, it passes:4344- `intent_summary` — 2–3 line intent (the caller's Step 1.3 output).45- `diff` — the full unified diff under review.46- `changed_files` — list of `{path, patch}` entries.47- `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.4849For `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`](./rules/plan-mode.md) for that input shape.5051Standalone (`/optimize-approach [report|apply]`) derives the diff-mode inputs from the current branch diff against `origin/main`.5253## Workflow5455| Phase | Name | Rule file | Gate |56| --- | --- | --- | --- |57| O0 | Read lessons | [`rules/self-improvement-loop.md`](./rules/self-improvement-loop.md) | Fast-tier read; skips silently if LoreKit `memory.*` not connected |58| O1 | Intent capture | this file | 1–2 line intent per changed approach unit |59| O2 | Optimality judgment | [`rules/optimality-rubric.md`](./rules/optimality-rubric.md) | Verdict `optimal` \| `suboptimal` per the 4-axis rubric + materiality bar |60| O3 | Quiet early-exit | [`rules/optimality-rubric.md`](./rules/optimality-rubric.md) | If `optimal`, return empty and stop |61| O4 | Deep understanding | this file + [`rules/optimality-rubric.md`](./rules/optimality-rubric.md) | `Skill("holistic-analysis", "refactor")` + `confidence(analysis)` on the alternative |62| O5 | Deliver | [`rules/report-mode.md`](./rules/report-mode.md) / [`rules/apply-mode.md`](./rules/apply-mode.md) | Report a proposal, or apply behind `confidence(code) ≥ 90 %` |6364### O1 — Intent capture6566Use `intent_summary` verbatim when supplied.67Standalone, derive it from PR title / body / commit messages / branch name.68For 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.6970### O2 — Optimality judgment7172Score each approach unit against the four axes in [`rules/optimality-rubric.md`](./rules/optimality-rubric.md): codebase-fit, simplicity, performance, robustness.73Reach one verdict per unit: `optimal` or `suboptimal`.74A 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`.7576### O3 — Quiet early-exit7778If every approach unit is `optimal`, return an empty finding list and stop.79Silence 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.80Still run the O5 end-of-run lesson write (a clean run is recurrence evidence for any lesson applied in O0).8182### O4 — Deep understanding (suboptimal units only)8384Before proposing, understand the change completely — never propose a "better way" from a shallow read.85861. Grep the relevant files, callers, and any existing utility or pattern the alternative would reuse.872. Invoke `Skill("holistic-analysis", "refactor")` to trace the execution path of the affected unit and generate + compare approaches.883. Gate the chosen alternative on `Skill("confidence", "analysis")`.89 **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`](./rules/report-mode.md)).90 **Apply:** requires the higher `analysis_confidence` ≥ 90 % bar as well — never apply an approach change the analysis is unsure about ([`rules/apply-mode.md`](./rules/apply-mode.md)).9192### O5 — Deliver9394- **report mode** → emit the proposal per [`rules/report-mode.md`](./rules/report-mode.md).95- **apply mode** → apply the top proposal per [`rules/apply-mode.md`](./rules/apply-mode.md), behind `confidence(code) ≥ 90 %`, scoped check, and revert-on-failure.9697Then run the fast-tier lesson write + promotion check in [`rules/self-improvement-loop.md`](./rules/self-improvement-loop.md).9899## Required Reading by Phase100101Load on demand — do not preload.102103| Phase | Files |104| --- | --- |105| O0, O5 | [`rules/self-improvement-loop.md`](./rules/self-improvement-loop.md) |106| O2, O3, O4 | [`rules/optimality-rubric.md`](./rules/optimality-rubric.md) |107| O5 (report) | [`rules/report-mode.md`](./rules/report-mode.md), [`templates/proposal.template.md`](./templates/proposal.template.md) |108| O5 (apply) | [`rules/apply-mode.md`](./rules/apply-mode.md) |109| plan mode | [`rules/plan-mode.md`](./rules/plan-mode.md) — approach review at plan time (aw-planner Phase 1) |110| wiring | [`agents/shared/rules/optimality-review.md`](../../../agents/shared/rules/optimality-review.md) — how the review agents call this skill |111| diagnose | [`rules/diagnostic-surface.md`](./rules/diagnostic-surface.md) |112113## Self-Improvement114115This skill runs a two-tier self-improvement loop keyed by the `optimize-approach-lessons` bucket (LoreKit tag `loop::optimize-approach-lessons`).116The 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.117A lesson reaching `seen_count >= 3` becomes promotion-eligible for the slow tier (`/create-skill diagnose optimize-approach`).118In `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`](../../../agents/shared/rules/codebase-knowledge.md)).119Full contract: [`rules/self-improvement-loop.md`](./rules/self-improvement-loop.md).120121## Core Principles1221231. **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`.1242. **Silence is the default outcome.** Most changes are already optimal enough — say nothing rather than manufacture a "better way".1253. **Understand before proposing.** A proposal requires a holistic trace and a `confidence(analysis)` gate — never a shallow "you could also…".1264. **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.1275. **Never block the verdict.** An optimality proposal is advisory (`suggestion` / `question`), like `scope-creep` — it never drives "Request changes".128129## Anti-patterns (one-liners — full list in the rules)130131- Proposing a "better way" that just restates a `code-quality` mechanical refactor.132- Manufacturing a suboptimal verdict on a change that clears the materiality bar.133- Applying an approach change across files outside the diff, or without the confidence gate.134- Emitting more than the cap of proposals — approach review is quality-over-quantity.135- Blocking the review verdict on an optimality finding.136137## Definition of Done138139- [ ] Verdict reached per approach unit (`optimal` → empty; `suboptimal` → proposal).140- [ ] Every `suboptimal` proposal carries a holistic trace and a `confidence(analysis)` score.141- [ ] apply mode gated on `confidence(code) ≥ 90 %` + scoped check + revert-on-failure.142- [ ] Fast-tier lesson write + promotion check ran at O5.
mthines