# Second-opinion audit

Get a review from a reader with no attachment to the work, then verify what it says before showing the user. The reviewer is a fresh subagent: it sees the work and the files, and none of this conversation, your reasoning or your conclusions. That clean start is where its independence comes from. Treat its findings as leads, never as truth.

Install locations: Claude Code reads this skill from `~/.claude/skills/second-opinion/` and starts it with `/second-opinion`. Codex reads it from `~/.codex/skills/second-opinion/` and starts it when the user mentions `$second-opinion`. Chat assistants use it pasted in or uploaded.

The skill needs no facts about the user, so there is no first-run interview.

## Step 1: Pick the mode

Decide from what the user pointed at. If it is unclear which piece of work to review, ask one question.

- **Plan or doc.** A plan, spec, design doc, proposal, README, or "is this approach sound". The reviewer reads the doc and checks its claims against any files it names.
- **Code change.** Uncommitted work, a branch, a commit, or a pull request. The reviewer runs `git status` and `git diff` itself (or `git diff <base>...HEAD` for a branch, `git show <sha>` for a commit), then reads the changed files.
- **Decision.** A business or life choice with no code: hiring, pricing, a move, a vendor, a deadline. The reviewer works from a neutral write-up of the facts and options.

If the work exists only in this conversation (a plan you drafted together, a decision the user described), write it to a temporary file first, word for word, with no commentary added. Use the tool's scratch or temp folder, never the user's project, unless they ask.

Ask for the stakes if you cannot tell them from context: what breaks, who is hurt, or what it costs if this goes wrong. Stakes tell the reviewer which failures matter.

## Step 2: Write the review prompt

Fill in `references/prompt-template.md` in this skill's folder. Pick 6 to 8 audit dimensions from `references/dimensions.md` and tailor each to this work: name the specific events, edge cases and people to probe. "Check for bugs" gets vague output. "What happens if the upload fails halfway, the user closes the app mid-save, or the login expires during a long session?" gets real findings.

For code and plans, find the key files yourself (search the project for what the work touches) and list 8 to 12 of them, each with a few words on why it matters. Use paths relative to the project root.

**Leave out your own opinion of the work.** This rule matters most. Do not say what you think is strong or weak, do not list concerns you already have as conclusions, do not say whether you wrote it or agreed with it, and do not hint at the answer you expect. Describe what the work proposes in neutral words. If you have a specific worry, include it only as an open question inside a dimension, phrased so either answer is possible.

Keep the prompt self-contained. The reviewer will not see anything you leave out.

## Step 3: Run it

Use what this tool has.

**The tool can start a subagent** (Claude Code's Agent tool, Codex subagents, and similar):
1. Start one fresh subagent with the prompt as its full instructions. Pass no conversation history.
2. Prefer a read-only agent type when the tool offers one that runs on a strong model. Otherwise use the general agent and rely on the prompt's read-only rule.
3. Tell the user it is running. A real audit can take several minutes. Wait for the report.
4. For code and plan audits in a git project, run `git status` afterwards and confirm the reviewer changed nothing. If it did, tell the user and restore nothing without asking.

**The tool cannot start a subagent** (ChatGPT, Claude.ai chat, other chat assistants):
1. Produce the prompt as one message in a single code block, ready to copy. Put the work itself inside it when it is short. When it is long, list the files the user must attach.
2. Tell the user: open a brand-new chat (a temporary or incognito chat where the app offers one, outside any project, so it cannot pull in memory or this conversation), attach the listed files, paste the prompt, and paste the full answer back here.
3. Wait for the pasted answer, then go to Step 4.

**Optional different-model review:** if the user has another AI's command-line tool installed (such as Codex or Gemini) and wants a different model's view, send the same prompt file to it in its read-only, non-interactive mode (for Codex: `codex exec -s read-only - < <prompt-file>`) and triage that answer the same way.

## Step 4: Triage before presenting (mandatory)

Never pass the report straight through. For each blocker and major finding, check the evidence it cites yourself:

- Code: open the cited file and line.
- Plan or doc: read the cited passage and any file it makes a claim about.
- Decision: compare against the facts the user gave. A finding that rests on facts you do not have is plausible but untested; note the question that would settle it.

Sort each one into a bucket:

- **Confirmed.** The source shows what the reviewer says.
- **Wrong.** The reviewer misread the source. Drop it and say why in one line.
- **Plausible, untested.** You cannot cheaply confirm or rule it out. Label it.

List minor findings in one line each, marked unchecked unless checking was cheap.

## Step 5: Report

Lead with the count: **"N findings, M held up."** N is every finding the reviewer returned. M is the confirmed ones.

Then, ranked by severity:
1. Confirmed findings: severity, the defect in one sentence, the evidence, and what it changes about the work.
2. Plausible but untested: the same, plus what would settle it.
3. Dropped as wrong: one line each with the reason.
4. Minor findings, briefly.

Then offer the next step: fold the confirmed findings into the plan, fix the code, or revise the decision write-up. Do not apply any change unless the user asks.

## Follow-ups

- **Re-audit after a revision.** Start a new fresh subagent with the same prompt plus a short note: "The work was revised to address: ... Focus on the revisions and anything you would still rank blocker." Triage again.
- **"Explain finding 3."** Answer from the report and the source. If the report cannot answer it, run a narrow new review on that one point.
- Keep the prompt and report in the temp folder. If the audit leads to a change in a committed doc, mention the audit in the change note; do not paste the full report into the doc.

---

The files named above are included below. Treat each one as the file it is named after.

---

<!-- references/dimensions.md -->

# Audit dimensions

Pick 6 to 8 per review and tailor each one. Name the actual events, files, people and dates in this work. A dimension that could apply to any project is too vague.

## Code

- **Races and ordering.** Two requests, tabs or workers touching the same record. Events that arrive out of order or twice. Read-then-write gaps. Merges that clobber newer data.
- **Interruptions.** The app is killed, backgrounded or loses network mid-step. A login or token expires during a long session. A job crashes halfway: what state is left, and does a retry fix it or double it?
- **Deleted and renamed code.** What still calls the removed function, field or route? Do old saved drafts, stored data or cached clients still load? Anything keyed by position or index that shifts when items are added or removed.
- **Gates that can be bypassed.** Permission checks done only in the UI. Validation skipped on one path. A feature flag, paywall or approval step that a direct request goes around.
- **Error paths.** What happens when the external service is down, slow or returns something unexpected? Are errors swallowed, retried forever, or shown to the user with private details?
- **Offline and sync.** Queued writes replayed after reconnecting. Conflicts between two devices. Stale data shown as current.
- **Cost and speed at real scale.** Queries inside loops, unbounded lists, large files in memory, paid API calls per item. What happens at ten or a hundred times today's volume?
- **Data changes.** Migrations on existing rows, defaults for new fields, timezone and date handling, rollback if the deploy fails halfway.
- **Inputs and secrets.** Untrusted input reaching queries, shells or HTML. Keys or personal data in logs, errors or the client.
- **Order of work.** A step that depends on something a later step builds.

## Plans and docs

- **Unstated assumptions.** What must already be true for this to work? Which ones has nobody checked?
- **Missing steps.** Gaps between steps where something has to happen and no one is named to do it.
- **Owners.** Every step has a person. Is anyone doing two jobs at once, or out during the window?
- **Dependency order.** Does a step need something that a later step produces? Can parallel steps collide?
- **What if X is late.** Pick the two or three slowest or least certain items. What happens to everything after them if they slip a week?
- **The way back.** If it goes wrong after launch, how do you undo it, and what is lost?
- **Done and measured.** How will anyone know it worked? Is the success measure written down before starting?
- **Claims vs. reality.** Statements about existing systems, files, numbers or agreements that the doc treats as fact. Check them.
- **Who is not told.** People, customers or teams affected who are not in the plan.
- **Scope creep and gaps.** Items that grew past the stated goal, and goal items that no step covers.

## Decisions

- **What has to be true.** List the beliefs this choice rests on. Which one, if wrong, flips the answer?
- **Cost of being wrong.** How bad is the worst realistic outcome, and how reversible is the choice? A cheap, reversible choice needs less proof than a locked-in one.
- **Options not considered.** Waiting, doing nothing, a smaller trial, a mix of two options, asking someone who has done it.
- **Who is affected.** Everyone the choice touches, including people with no say in it. What do they lose or gain?
- **Second-order effects.** What changes six or twelve months later as a result? What does this choice make harder next time?
- **Timing.** Is the deadline real? What is gained or lost by deciding later?
- **Incentives and sources.** Who supplied the key facts, and do they gain from one answer?
- **Base rates.** How often does this kind of choice work out for others in the same spot?
- **Money and time, honestly.** Full costs including setup, upkeep, the person-hours, and what else that time and money could do.

---

<!-- references/prompt-template.md -->

# Review prompt template

Copy the block below, fill every `<...>` slot, and delete lines that do not apply to the mode. Each section earns its place: CONTEXT sets which failures matter, the read list and VERIFY section force the reviewer into the source, the tailored dimensions aim it, and the OUTPUT format makes the findings checkable in triage.

Do not add your own view of the work anywhere in the prompt. Describe it neutrally.

```
You are auditing <what: a plan / a code change / a design doc / a decision> for
blind spots. Be adversarial: your job is to find what it misses or gets wrong,
not to summarize or praise it. Back every finding with evidence from the source.

READ-ONLY. Do not create, edit, move or delete any file. Do not run commands
that change anything. Reading files and running git status, git diff, git log
and git show are allowed.

CONTEXT
<2-4 lines: what the project, team or situation is, and the STAKES, e.g.
"a small online shop; this change touches checkout, so a bug loses orders" or
"a two-person team choosing a vendor they will be locked into for two years".>

READ FIRST
<Plan or doc mode: the path to the doc, or "the attached document".>
<Code mode: "These changes are uncommitted in the working tree. Run git status
and git diff (and git diff --staged) first, then read the files below."
For a branch: "Run git diff <base>...HEAD and git log <base>..HEAD first."
For a commit: "Run git show <sha> first.">
<Decision mode: "The decision is written up below." Then paste the neutral
write-up: the question, the options, the facts and numbers given, the
constraints, the deadline.>

WHAT IT PROPOSES
<One short paragraph in neutral words: what the work does or decides. No
judgement of whether it is good.>

VERIFY CLAIMS AGAINST THE SOURCE
Do not trust the work's own assertions. Check them against these files:
- <path relative to project root> (<why it matters to this audit>)
- <...8-12 files at most>
<Decision mode: "Check each claim against the facts stated above. Say plainly
when a conclusion depends on a fact that is not given.">

AUDIT FOR
1. <dimension, with the specific failure cases to probe>
2. <...>
<6-8 numbered dimensions, tailored to this work. Phrase each as questions to
probe, not as suspected answers.>

OUTPUT
A ranked list of findings, most severe first. For each:
[severity: blocker / major / minor] - the claim or assumption in the work ->
what the source actually shows (file:line, or the quoted passage or fact) ->
a concrete failure scenario -> a suggested fix.
No praise and no restating the work. If a claim checks out, leave it out.
If you could not check something, say so instead of guessing.
```

## Chat version (no subagent)

When the person will paste the prompt into a new chat, make two changes:

- Replace the READ-ONLY paragraph with: "Work only from what is pasted or attached here. If you need a file that is not attached, name it and say what you would check."
- Replace file paths with "the attached file `<name>`", and put short work (under a few pages) inside the prompt between `--- START OF WORK ---` and `--- END OF WORK ---` lines.

For code reviews in chat, ask the person to attach the diff (or the changed files) and say which files changed.

## Re-audit note

Append this for a second round:

```
REVISION
The work was revised to address: <list the changes, one line each>.
Focus on the revisions and on anything you would still rank blocker.
```
