advice

Files (1)

• SKILL.md

SKILL.md (first lines)

# /advice — Token-Efficient Second Opinion

**Replaces `advisor()`. Never call advisor() — use this instead.**

## When invoked

`/advice [optional: specific question]` — invoked manually or automatically at a decision point.

## Step 1: Build the review packet

From the current conversation, extract:
- **Decision** (3–5 sentences): what specifically needs a second opinion — be concrete about constraints and tradeoffs
- **Pointer**: where the reviewer can read the change *itself* — a PR number, a `base...head` ref, or an explicit file-path list. Include `git diff --stat` (or `gh pr diff --name-only`) so the reviewer sees the shape of what it is about to read.

If no specific question was passed, infer from most recent context.

**Send the pointer, not a transcription.** Every reviewer transport in Step 2 is an *agent* that can read the repo for itself — Codex and Opus run in independent exact-SHA clones, `cursor -p` has access to write and shell tools, `agy`/`claude -p` run with permissions pre-approved, and `/secondo` gathers its own `git diff origin/main...HEAD`. Handing them a pre-chewed excerpt does not save them a fetch; it *removes* their ability to look. Give the pointer and let each one pull the context it decides it needs.

### The inline-artifact fallback (≤150 lines) — narrow, and it caps the verdict

Inline an artifact only when the reviewer genuinely cannot fetch: no repo access, no PR, or the subject is not in version control (a plan, a pasted stack trace, an architecture sketch). Then keep it under ~150 lines.

**A verdict built on a truncated inline artifact may not be `APPROVED`.** Record `REVIEWED: <n> of <total> lines (<what was omitted>)`, carry it into the synthesis, and emit `WITHHELD` — see Quorum. This is not a formality: across the last 300 merged PRs in `jleechanorg/worldarchitect.ai`, **65% exceed 150 changed lines** (median 349), and for those, a 150-line cap shows a reviewer a median **22.5%** of the diff. A gate that says `APPROVED at <SHA>` after seeing a fifth of the change is asserting something it did not check.

## Step 2: Fan out the reviewers in parallel

**Size/risk gate first.** For low-risk diffs (docs/tests/config-only, or under ~100 changed production lines with no schema/security/prompt-contract surface), Reviewer A alone (Codex + Opus — two independent verdicts, so the ≥2-reviewer quorum for `APPROVED` still holds) satisfies the gate; skip B/C. Reserve the full A+B+C fan-out for diffs touching production behavior, schemas, security, or above that threshold. The quorum, coverage, and inline-artifact rules below apply unchanged regardless of which lanes run.

Spawn every selected reviewer in a single message. **A and B are the portable core** — they work on any machine. **C depends on personal infrastructure** and is skipped, not faked, when unavailable.

---

**Reviewer A — Primary pair fired IN PARALLEL:**

**Codex + Opus run concurrently when both are available.** Each reviewer reads
the change independently and returns its own verdict. Use the executable runner
below: descriptive prose or a foreground Codex call followed by an Opus spawn
does not satisfy this contract.

Use the same review packet for both reviewers:

```
You are a senior engineer giving a focused second opinion.

DECISION:
[decision, 3–5 sentences]

WHAT TO REVIEW:
[PR number / base...head ref / file-path list, plus diff --stat]

Read the change yourself — do not rely on any summary in this prompt.
Read as much of it as your judgment requires. If you could not read
what you needed, say so in COVERAGE rather than guessing.

Return exactly:
VERDICT: [recommended approach, one line]
REASONING: [3–4 sentences]
RISK: [main risk, one sentence]
COVERAGE: [what you actually read; note anything you could not reach]
CONFIDENCE: [high / medium / low]
```

Write that packet to a temporary file, capture the exact review SHA, and invoke:

```bash
REVIEW_SHA="$(git rev-parse HEAD)"
ADVICE_TMP="$(mktemp -d)"
ADVICE_RUNNER="${CLAUDE_HOME:-$HOME/.claude}/skills/advice/scripts/run_primary_pair.py"
python3 "$ADVICE_RUNNER" \
  --repo "$(git rev-parse --show-toplevel)" \
  --ref "$REVIEW_SHA" \
  --packet-file "$ADVICE_TMP/review-packet.txt" \
  --output-dir "$ADVICE_TMP/results" \
  --timeout-seconds 1200 \
  --timeout-grace-seconds 2
```

Create `$ADVICE_TMP/review-packet.txt` before invoking the runner. The output
directory is deliberately outside the repository. Read `codex.txt`, `opus.txt`,
and `receipt.json`; the receipt records the resolved SHA, each transport, launch
times, each clone SHA, cleanup status, and any changed original-repository
fingerprint components. The
input checkout must be clean, including untracked files. The runner refuses a
dirty checkout because those changes are not represented by the requested SHA.

The runner creates two independent disposable clones with `git clone --no-local`,
removes their `origin` remotes, and detaches both at the exact same SHA. It then
starts A1 and A2 behind one concurrency barrier, gives them disjoint output
files, and removes the clones afterward. It preserves the requested
full-permission transports explicitly: `codex exec --yolo` for A1 and
`claude -p --model opus --dangerously-skip-permissions` for A2. Independent
clones prevent reviewer writes to refs, config, or hooks from sharing the
original repository's `.git` state; they are deliberately **not** an OS security
sandbox. If the original checkout, refs, local config, or hooks change, the
runner fails closed and its verdicts may not be used.

While each reviewer root is alive, the runner samples the macOS/Linux process
tree, retains PID plus process-start identity for discovered descendants even
after reparenting, and on timeout terminates those descendants before/with the
root process group. The receipt lists discovered, signaled, and surviving PIDs
plus whether termination was verified. Bounded drain then guarantees that a
remaining inherited pipe cannot block runner return or clone cleanup.

This lifecycle supervision does not change full-permission mode and is not an
OS sandbox: it does not restrict network, environment, or process creation. An
arbitrary daemon that forks, reparents, and disappears from the sampled lineage
before the first observation can evade user-space process-tree tracking. For
descendants observed while the reviewer root is alive, a surviving verified PID
is recorded as a termination failure rather than silently treated as contained;
after successful cleanup the runner exits 7 even if the peer returned a verdict.

Each primary reviewer has a bounded runtime. `--timeout-seconds` sets the
per-lane limit and defaults to 1200 seconds (20 minutes).
`--timeout-grace-seconds` sets the bounded post-kill output-drain grace and
defaults to 2 seconds; both values must be positive. A timeout kills the primary
process group, drains output only for that grace, then closes inherited output
pipes if they remain open. The attempt records `failure: timeout` and
`forced_pipe_close`; the peer may still supply the sole primary verdict. If both
time out, the runner exits 4 and A3 applies. Clone cleanup and receipt writing

From jleechanorg/jleechanbrain, MIT.

More from jleechanorg/jleechanbrain