@nklisch/pi-agile-workflow 0.15.3

package/skills/perf-scout/references/peer-review-pass.md

@@ -0,0 +1,150 @@
+# Cross-Model Peer Pass — Perf-Scout
+
+> The mechanics of Phase 5. This is the skill's headline value: a **different
+> model class** has different blind spots, so it's the single best source of the
+> angles your scouts collectively missed — and a sharp pruner of ideas that don't
+> hold up. Run it by default; only skip on `--no-peer` (and say what's being lost).
+
+## Why a different model, not just another pass
+
+Your scouts share your model's training and habits, so they tend to miss the same
+things. The value of peeragent here is **independent blind spots**, not a more
+authoritative answer. A Codex/Gemini reviewer will flag generic ideas you rated
+too highly and propose strategies your lenses didn't reach. That asymmetry is the
+whole point — their misses are your catches and vice versa.
+
+This mirrors the global rule: *don't use peeragent when the peer would be the same
+model class as the host.* If the only available peer is the same class as you, the
+fallback sub-agent (below) is the better choice precisely because a fresh,
+context-isolated agent still gives *some* independence.
+
+## Step 1: Pick the reviewer
+
+**Preferred — different model class via peeragent.** The whole value is blind-spot
+diversity, so pick the peer that **maximizes training difference from the host**,
+not a "better" model. Resolve the concrete host→peer pairing (Claude host →
+codex/gemini/zai; Codex host → claude opus/gemini/zai; Gemini host → claude opus/
+codex/zai; GLM host → claude opus/codex/gemini) and the exact `--agent/--model/
+--effort` flags from [../../principles/references/models.md](../../principles/references/models.md)
+§4 and §7 — keep the matrix in one place rather than duplicating it here.
+
+Resolve the wrapper before calling; never assume `peeragent` is on `PATH`:
+
+1. If `PEERAGENT_BIN` names an executable, use it.
+2. Otherwise resolve the peeragent plugin's bundled wrapper (`bin/peeragent`
+   under the peeragent plugin/checkout location).
+3. Use bare `peeragent` only if a bundled path can't be found and
+   `command -v peeragent` succeeds. If a bare call fails with `command not
+   found`, retry once with the bundled path before giving up.
+
+Run the wrapper in the host harness's outside-sandbox command mode so the peer
+CLI inherits normal network/auth/process env. Do **not** pass `--full-access` —
+review never needs it.
+
+When the target is a top-tier reasoning peer (Opus-class, xhigh Codex/GLM),
+budget real wall time. Large deck reviews commonly take 10 to 30 minutes, and
+the wrapper may be quiet for most of that time. Do not treat "no response after a
+few minutes" as a hang, and do not switch to the fallback unless the process
+exits, reports failure, or exceeds a timeout chosen for top-tier review work.
+
+**This pass is the adversarial phase.** For a deep or complex deck, precede it
+with a **completeness/advisory** pass from a *second* different class if
+available — does the deck miss whole lenses or high-leverage angles before you
+start pruning? That realizes the 2-class rule (advisory class A, adversarial
+class B). See the two-phase ordering in
+[../../principles/references/models.md](../../principles/references/models.md) §6.
+
+**Fallback — fresh max-effort sub-agent.** Use this when peeragent is
+unavailable, the wrapper returns `failed`/`blocked`, or the only peer would be the
+same model class. Spawn one in-harness agent at the strongest reviewer setting
+and give it **only** the codebase, the lens catalog (`references/`), and the idea
+deck — deliberately NOT your scouts' reasoning or notes — so it reviews with
+independent context.
+Context isolation is what buys independence when model diversity isn't available.
+Frame it explicitly as an adversarial gap-finder (same three asks below).
+
+State in the report which reviewer ran (peer class + effort, or "fallback
+sub-agent — peeragent unavailable") so the cross-model value is transparent.
+
+## Step 2: Ask for three things
+
+Write the aggregated, ranked idea deck to a temp file and pass it via
+`--prompt-file` (the deck is large). Ask the reviewer — without leading it toward
+your conclusions — for exactly these, in this order of importance:
+
+1. **Gaps (most valuable).** High-leverage performance angles, strategies, or
+   whole *lenses* this deck missed. "What would a specialist from a demanding
+   domain (a database engine, a game engine, an HPC/HFT shop, a GPU programmer)
+   notice here that isn't on this deck?" This is why a different model is worth
+   the call.
+2. **Weak ideas to prune.** Which candidates are implausible, generic, wrong about
+   the code, or not worth a measurement — and why. Verify against the actual
+   files; don't take the reviewer's word blindly.
+3. **New candidates.** Concrete new ideas in the same hypothesis framing (title,
+   borrowed-from, location, the idea, why it might help, validate-by). Same
+   honesty bar: speculative, with a validation path, never asserted as real.
+
+Always include the **no-recursion instruction**: tell the reviewer not to call
+peeragent's own `peer`/`peer-review` skills or the `peeragent` wrapper to delegate
+back out — it may use its own harness's internal sub-agents, but recursive
+peeragent delegation loops host→reviewer→host and burns budget. The reviewer is
+the endpoint.
+
+A serviceable prompt shape:
+
+> You are an independent performance reviewer with a different perspective from
+> the agent that produced this. Attached is a deck of *candidate* (speculative,
+> unvalidated) performance ideas for the repo at `<cwd>`, organized by strategy
+> lens. The files referenced are in this same repo — read them directly.
+>
+> Give me the good, the bad, and the ugly:
+> 1. GAPS — what high-leverage angles, strategies, or whole categories did this
+>    deck miss? What would a specialist from databases / game engines / HPC / GPU
+>    / distributed systems spot here that isn't listed?
+> 2. WEAK IDEAS — which listed ideas are implausible, generic, wrong about the
+>    code, or not worth measuring, and why?
+> 3. NEW CANDIDATES — concrete additional ideas: title, what domain it's borrowed
+>    from, file:line, the transform, why it *might* help, and how to validate.
+>
+> These are hypotheses, not proven wins — keep that framing; never assert a
+> speedup is real. Cite file:line. Review this directly — do NOT call the
+> peeragent peer/peer-review skills or wrapper to hand it off again; use your own
+> harness's sub-agents if you need help.
+
+## Step 3: Integrate honestly
+
+Read the response through the same lens as `/peer-review`'s honest-evaluation
+step — accept concrete, verifiable points; push back on taste-dressed-as-fact and
+on claims that misread the code (verify first).
+
+- **Prune** ideas you agree are weak. Don't silently delete them — mark them
+  `pruned by peer: <reason>` so the report shows what the cross-model pass
+  removed. (A pruned generic idea is a real win: it sharpens the deck.)
+- **Add** accepted gap/new ideas, tagged `source: peer-<agent>` (or
+  `source: peer-fallback`). Re-run them through Phase 4 ranking so they tier
+  alongside the rest.
+- **Fan out one more scout** if the peer named a missed *lens* with real signal —
+  spawn that single Phase-3 scout, then re-aggregate and re-rank. This is the one
+  case where the peer pass triggers more generation.
+
+## Step 4: One pass, usually
+
+Unlike `/peer-review`'s 3-5 convergence loop, idea generation isn't a converging
+artifact — a deck doesn't "stabilize," it just accumulates. One strong pass is
+usually right. Loop a second time only if the peer opened a genuinely new
+high-value direction (e.g. a missed lens that produced Investigate-first ideas)
+and you want that direction reviewed too. Never pad passes.
+
+## Step 5: Record it for the report
+
+Capture, for the report's "Cross-model peer pass" section and the user summary:
+- Which reviewer ran (agent + effort, or fallback) — be honest if the fallback
+  was used.
+- Count pruned + the gist of why.
+- Count added + how many landed in Investigate-first (the headline: "the peer
+  surfaced N angles we missed, M of them top-tier").
+- Whether a follow-up scout was fanned out for a missed lens.
+
+If the peer pass could not run at all (no peer, fallback also failed), say so
+plainly in the report — a deck without an independent pass is weaker, and the user
+should know.

package/skills/perf-scout/references/report-template.md

@@ -0,0 +1,148 @@
+# Perf-Scout Report Template
+
+> Used by `perf-scout` to write `perf-scout-report.md` at the repo root. Fill the
+> placeholders; drop sections with zero entries. The whole document describes
+> *candidate ideas* — unvalidated hypotheses. Keep that framing throughout; never
+> phrase an idea as a realized improvement.
+
+```markdown
+# Perf-Scout Report
+
+**Generated**: <ISO-date>
+**Scope**: <"whole repo" OR path/NL scope>
+**Files considered**: <N>
+**Workload shape**: <request-service / batch-pipeline / realtime-sim / library-kernel / mixed>
+
+> ⚠️ Everything below is a **candidate optimization** — a speculative, unvalidated
+> hypothesis borrowed from another domain's playbook. Nothing here has been
+> measured. Validate before acting, usually via `/agile-workflow:perf-design`.
+
+## Stack & shape profile
+
+- Languages / runtimes: <list>
+- Workload shape: <dominant shape(s) and why>
+- Hot-ish regions (guessed, not profiled): <list>
+- Already present (not re-proposed): <caches / pools / SIMD / indexes / etc.>
+
+## Lens opportunity density
+
+> Opportunity signal (how much plausible headroom each lens found), NOT a code
+> quality grade. High = lots to investigate here; low = little obvious headroom.
+
+| Lens | Relevance | Opportunity (0-10) | Ideas (Investigate / Worth-a-look / Long-shot) |
+|---|---|---|---|
+| Algorithmic & data structures | most | X/10 | 2 / 1 / 0 |
+| Memory & data locality | relevant | X/10 | 1 / 2 / 1 |
+| Parallelism & vectorization | relevant | X/10 | 0 / 1 / 2 |
+| GPU & accelerators | skip | — | — |
+| Caching & memoization | most | X/10 | 1 / 1 / 0 |
+| I/O & batching | most | X/10 | 2 / 0 / 1 |
+| Distributed systems | relevant | X/10 | 0 / 1 / 1 |
+| Game-engine & realtime | skip | — | — |
+| Database & storage internals | relevant | X/10 | 1 / 0 / 1 |
+| Compiler, runtime & language | relevant | X/10 | 0 / 2 / 1 |
+| Approximation & precomputation | relevant | X/10 | 1 / 0 / 0 |
+
+## Top 5 to investigate first
+
+> The strongest bets, spread across domains. One line each.
+
+1. **<title>** — `<file:line>` · borrowed from <domain> · <lens> · <Leverage>/<Applicability>/<Cost>
+2. ...
+3. ...
+4. ...
+5. ...
+
+## Cross-model peer pass
+
+- **Reviewer**: <peer agent + effort, e.g. "codex --effort xhigh"> OR <"fallback sub-agent (peeragent unavailable)"> OR <"not run (--no-peer)">
+- **Pruned**: <n> weak/generic ideas removed — <one-line gist of why>
+- **Added**: <n> new ideas surfaced by the peer (<m> landed Investigate-first)
+- **Follow-up scout**: <lens fanned out for a missed lens, or "none">
+
+> The value of this pass is the angles a single model missed. If it didn't run,
+> this deck has no independent check — treat it as weaker.
+
+## Ideas by priority
+
+### Investigate-first (<n>)
+
+#### <title>
+- **Lens**: <lens> · **Borrowed from**: <domain>
+- **Location**: `<file:line>`
+- **Leverage / Applicability / Cost**: <High|Med|Low> / <Likely|Plausible|Speculative> / <Low|Med|High>
+- **The idea**: <2-4 sentences: the specific transform and the technique it borrows.>
+- **Why it might help**: <speculative mechanism — "might", never "will".>
+- **Validate by**: <metric / benchmark / "profile via perf-design">
+- **Risk**: <one line>
+- **Source**: <scout | peer-codex | peer-fallback>
+- **Parked**: `perf-scout-<slug>` *(or `not parked: --no-park` / `not parked: no substrate` / `duplicate of perf-scout-<slug>`)*
+- *Also surfaced by*: <other lens, if duplicate>
+
+<repeat for each Investigate-first idea>
+
+### Worth-a-look (<n>)
+
+<same shape>
+
+### Long-shot (<n>)
+
+> Long-shots are listed here but **not parked to the backlog by default** (they'd
+> add speculative noise). Re-run with `--park-all` to park them too.
+
+<same shape — may be compressed to one-liners if many>
+
+### Pruned by peer (<n>)
+
+> Ideas the cross-model pass flagged as weak/generic/wrong. Listed for
+> transparency; not parked.
+
+- **<title>** — `<file:line>` — pruned: <reason>
+
+## Lenses skipped
+
+| Lens | Why |
+|---|---|
+| <lens> | <e.g. "no realtime/per-frame loop", "single-process, no distribution"> |
+
+## Backlog parking summary
+
+| Metric | Count |
+|---|---|
+| Ideas parked this run | <n> |
+| Duplicates skipped (already in backlog) | <n> |
+| Opt-out (`--no-park`) | true / false |
+| Substrate present | true / false |
+
+> Parked ideas live at `.work/backlog/perf-scout-*.md` with `idea_origin: scout`.
+> Promote any to tracked work via `/agile-workflow:scope <id>`, or hand to
+> `/agile-workflow:perf-design` to measure. Find them all with:
+> `grep -l '^idea_origin: scout$' .work/backlog/*.md`.
+
+## Scout gaps
+
+> Any scout that errored or returned inconclusive results. Re-run that lens alone
+> with `--lenses <lens>` if you want.
+
+- <lens>: <what went wrong, or "—" if all clean>
+
+## Next steps
+
+- Hand a top idea to `/agile-workflow:perf-design <id>` to profile and confirm
+  (the only place a hypothesis becomes a measured win).
+- `/agile-workflow:scope` to promote ideas into tracked work.
+- Re-scout a single lens with `--lenses <lens>` to dig deeper.
+```
+
+## Rules
+
+- Always include the ⚠️ unvalidated banner up top and keep speculative phrasing
+  throughout. The report's credibility comes from being honest that it's a
+  brainstorm, not an audit.
+- Show the lens table even when rows are skipped — empty rows signal coverage.
+- Group ideas by priority tier, then by lens within each tier.
+- Sort within a tier by `file:line` for diff-friendliness.
+- Don't list the same idea under multiple tiers — pick its tier and cross-link
+  duplicates with "Also surfaced by".
+- Always include the cross-model peer section, even if it just says the pass
+  didn't run and why — that absence is information.