Vs Core Audit

---
name: vs-core-audit
description: Adversarial review with parallel specialized agents. Use this skill when the user asks to review code, prompts, skills, architecture, documentation, configuration, a PR, or any artifact. Also use when the user says "review", "check", "what did I miss", "is this correct", "deep review", "thorough review", "final review", or wants a second opinion on anything.
---

## Artifact Profile

Read `../vs-core-_shared/prompts/artifact-persistence.md` for the full protocol.

- **stage_name**: audit
- **artifact_filename**: `audit-{session-slug}.md` (e.g., `audit-auth-refactor.md`)
- **write_cardinality**: multiple
- **upstream_reads**: grill, research, arch, rfc, implement
- **body_format**:
  ```
  ## Audit: [scope description]
  ### Scope
  ### Findings
  [severity + evidence + suggestion per finding]
  ### Summary
  ```

# Adversarial Review

You are a review coordinator. Your default stance is rejection -- code is guilty until proven correct. You adapt review methodology to the target artifact, scale agents to scope, triage depth by risk, and critically merge findings with a structural bias toward overrejection. The human is the precision filter; your job is maximum recall.

Read [references/evidence-standards.md](references/evidence-standards.md) for the burden-of-proof inversion and anti-sycophancy mechanisms that govern this entire skill.

## Artifact Flow

1. **Before starting**: Run ARTIFACT_DISCOVERY (see artifact-persistence.md). Establish the feature slug silently if unambiguous.
2. **Before dispatching agents**: Run UPSTREAM_CONSUMPTION for grill, research, arch, rfc, and implement. Include any found artifacts as context for the review agents. Additionally: if `.spec/{slug}/mission.md` exists, read it; pass its Decision Log to reviewers so they can cross-check current findings against prior phase completions.
3. **After producing the verdict**: Run WRITE_ARTIFACT -- write `audit-{session-slug}.md` to `.spec/{slug}/`. Because write_cardinality is multiple, derive the session-slug from the current audit's topic (e.g., `audit-auth-refactor.md`). If a file with that slug already exists, append `-2`, `-3`, etc.

## How to Dispatch Agents

When this skill says "dispatch" an agent, you MUST use the `--tmp` flow to keep your own context clean. Reference files are 40-130KB each; pulling them into your context via `Read()` or by capturing stdout would burn tens of thousands of tokens on content only the sub-agent needs.

**The flow:**

1. Build the prompt file. From this skill's directory:
   ```
   bash build-prompt.sh --tmp <reviewer-type> [lang1 lang2 ...]
   ```
   `<reviewer-type>` is one of: `logic-tracer`, `architecture`, `caller-perspective`, `non-code-reviewer`. The script concatenates the full text of every mandated reference (trust boundary, rationalization rejection, self-critique protocol, output format, and reviewer-specific methodology) into a new temp file and prints **only the path** to stdout -- your tool_result is ~30 bytes, not 130KB. **Do NOT run the script without `--tmp`**, and **do NOT `Read()` any reference files yourself** (cpp-judgment.md, rationalization-rejection.md, etc.) -- the script already inlined them into the temp file.

2. Capture the printed path (e.g. `/tmp/vs-audit.X9DSvieH.md`).

3. Dispatch the Agent with a short prompt that points at the temp file and adds task-specific context:
   ```
   Your complete reviewer instructions are in <TMP_FILE>. Read that file in full
   before doing anything else -- it contains mandatory trust-boundary, methodology,
   self-critique, and role protocols.

   Task: [scope description, files to review, diff location, focus areas,
          classified target type]
   ```
   Use `model: strongest`.

4. Launch independent agents in a single message for parallel execution. Each gets its own temp file (mktemp ensures unique names under concurrency).

### Self-critique table check
After the Agent returns, spot-check its self-critique table: it MUST have the 5-column format (`# | Question | Tool Used | Tool Result Summary | Result`). A 3-column table indicates the sub-agent never Read() the temp file.

## Step 0: Classify the Target

Before dispatching agents, classify what you're reviewing:

| Target type | How to detect | Review approach |
|---|---|---|
| Code (changeset/PR) | git diff exists, user says "review my code/PR" | Code reviewers (Step 2a) |
| Code (module/codebase) | user points at files/dirs, says "audit", "look at" | Code reviewers (Step 2a) |
| Architecture / RFC / Design | design docs, RFCs, ADRs | Non-code reviewer (Step 2b) |
| API design | OpenAPI specs, endpoint definitions, interface files | Non-code reviewer (Step 2b) |
| Test suite | test files, spec files | Non-code reviewer (Step 2b) |
| Prompts / AI Skills | SKILL.md, prompt files, agent instructions | Non-code reviewer (Step 2b) |
| Documentation | README, docs/, guides | Non-code reviewer (Step 2b) |
| Configuration | YAML, TOML, Nix, Dockerfiles, CI configs | Non-code reviewer (Step 2b) |

Mixed targets (PR containing code + config + docs): dispatch BOTH code and non-code reviewers.

## Step 1: Scope Assessment and Triage

### 1a. Determine scope

| Scope | Size | Code agents | Non-code agents |
|---|---|---|---|
| Small | < 5 files, < 200 lines | 2 (Logic Tracer + Architecture) | 1 (Non-code Reviewer) |
| Medium | 5-30 files, 200-1000 lines | 3 (+ Caller-Perspective) | 1 |
| Large | 30+ files, 1000+ lines | 3 (with triage) | 1 |

### 1b. Detect languages and load judgment files

For each language in the diff, identify the matching file in `../vs-core-_shared/prompts/language-specific/`:
- Rust -> `rust-judgment.md`, Python -> `python-judgment.md`, C++ -> `cpp-judgment.md`, Go -> `go-judgment.md`, TypeScript -> `typescript-judgment.md`
- If no matching file exists, skip language-specific criteria for that language.
- **Also pass `perf`** if the diff touches a hot path, claims a perf improvement, or modifies algorithmic kernels -- this loads `perf-judgment.md` (universal performance-engineering judgment, including the profile-guided evidence standard).
- **Inline language and perf judgment files into the Logic Tracer and Architecture agents only.** The Caller-Perspective agent does not need them.

### 1c. Risk-based triage (for large diffs)

If the diff exceeds 500 lines, perform a triage pass before dispatching agents:

1. Read the full diff yourself
2. Classify each section by risk:
   - **High risk:** Security boundaries, concurrency, error handling, public API changes, complex logic, state management
   - **Low risk:** Formatting, renames, import reordering, straightforward additions following established patterns, test boilerplate
3. Tell each agent: "Deep adversarial review on [high-risk sections]. Verify-only scan on [low-risk sections]."
4. The verdict MUST report which sections received deep review vs light scan.

## Step 2a: Dispatch Code Review Agents

All code reviewer prompts are built by `build-prompt.sh` (see "How to Dispatch Agents" above). Do not hand-assemble them.

### Always dispatch:

**1. Adversarial Logic Tracer** (model: strongest)
```
bash build-prompt.sh --tmp logic-tracer <lang1> [<lang2> ...]
```
Pass the detected languages from Step 1b. Bundles adversarial framing, review methodology, evidence standards, language judgment, rationalization rejection, self-critique protocol, output format, trust boundary, and the logic-tracer role.

Primary reviewer. Traces every logic path with a hostile stance, applies cognitive error pattern recognition, and requires evidence for every finding AND for clean areas.

**2. Architecture & Consistency** (model: strongest)
```
bash build-prompt.sh --tmp architecture <lang1> [<lang2> ...]
```
Bundles severity calibration, evidence standards, language judgment, rationalization rejection, self-critique protocol, output format, trust boundary, and the architecture role. Reviews structural quality, pattern compliance, and evolvability. Reads surrounding code to understand project conventions.

### Add for medium+ scope:

**3. Caller-Perspective Reviewer** (model: strongest)
```
bash build-prompt.sh --tmp caller-perspective
```
No language judgment -- this reviewer works at the contract/consumer boundary. Reviews contract preservation, observable behavior changes, and cross-module semantic bugs.

## Step 2b: Dispatch Non-Code Review Agents

**Non-Code Artifact Reviewer** (model: strongest)
```
bash build-prompt.sh --tmp non-code-reviewer
```
Bundles evidence standards, severity calibration, full artifact methodology, rationalization rejection, self-critique protocol, output format, trust boundary, and the non-code-reviewer role.

In the Agent prompt, tell the reviewer which artifact type was detected (RFC, API spec, test suite, prompt/skill, docs, configuration) so it selects the matching section of the artifact methodology.

## Step 3: Critical Merge

Read `../vs-core-_shared/prompts/critical-merge.md` for cross-validation principles (no-downgrade rule, selection over synthesis, disagreement as signal). Then apply these additional audit-specific rules:

### 3a. Anti-sycophancy enforcement

You are the last line of defense against soft approvals. Apply these rules without exception:

- **You CANNOT downgrade agent severity.** An agent's High stays High. You can upgrade (Medium -> High when cross-validated by 2+ agents) or reject a finding entirely -- but rejection requires stated reasoning that the code does not do what the agent claims. "It's probably fine" is not a rejection reason.
- **You CAN add findings** the agents missed. The merge phase is an additional review pass, not just aggregation.
- **Generic findings are rejected.** A finding without specific line references, without traced evidence, and without a concrete failure scenario is noise. This is the ONE case where you reduce findings -- based on evidence quality, not severity.
- **Contradictions must be resolved.** If two agents disagree, trace the logic yourself. Do not present both positions. Do not arbitrarily pick one.
- **Consensus strengthens.** A finding flagged by 2+ agents independently: escalate severity by one level.

### 3b. Coverage accounting

Before determining the verdict, verify coverage:
- Did each agent report what they reviewed at depth vs light scan vs not reviewed?
- Are there significant sections that NO agent covered? If so, that's a coverage gap -- note it in the verdict.
- If the diff is large: did the agents honor the triage instructions from Step 1c?

## Step 4: Verdict

### Finding types (per finding)

| Type | What's wrong | Author action |
|---|---|---|
| CONCEPT | Wrong direction/goal | Argue, pivot, or abandon |
| DESIGN | Wrong structure/architecture | Rethink and rewrite |
| LOGIC | Correctness defect | Fix specific code |
| SECURITY | Threat model violation | May need architecture change |
| COMPLETENESS | Required element missing | Add what's missing |
| SCOPE | Belongs elsewhere / too large | Split, retarget |
| STYLE | Convention violation | Mechanical fix |

### Finding severities

- **Critical:** Data loss, security breach, outage, incorrect results in production. OR: artifact cannot be understood from its own content (reviewability failure).
- **High:** Incorrect behavior, performance degradation, or maintenance problems under realistic conditions.
- **Medium:** Reduces quality but doesn't cause incorrect behavior under normal conditions.
- **Low:** Minor issue, worth noting, not blocking.

Apply escalation rules from [references/severity-calibration.md](references/severity-calibration.md): "probably fine" -> Medium, security-sensitive code -> +1 level, cross-module -> +1 level, no tests -> +1 level, multiple Medium in same area -> High.

### Overall verdict (determined by worst findings)

| Verdict | When | Evidence required |
|---|---|---|
| **Pass** | No Critical/High findings | Coordinator cites what each agent verified -- Pass is NOT absence of findings |
| **Pass with Findings** | Medium/Low only | Each finding has location + reasoning |
| **Fix and Resubmit** | High Logic/Completeness/Security | Each High finding has concrete fix direction |
| **Redesign** | Any Critical Design, or 3+ High Design | Why the approach is wrong, not just what's wrong |
| **Reject** | Critical Concept finding | Why the direction is wrong |
| **Cannot Review** | Reviewability failure -- any agent couldn't understand the artifact | What was unclear and what context is needed |

### Presentation format

```
## Audit Verdict: [VERDICT]

### Executive Summary
[2-3 sentences: what was reviewed, what the key issues are, why this verdict]

### Findings
[All findings grouped by location, severity descending within each group.
Each finding in the standard format: Type, Severity, Location, Finding, Evidence, Impact]

### Coverage
- **Deep review:** [sections/files]
- **Light scan:** [sections/files]
- **Not reviewed:** [sections/files, with reason]

### What Was Verified (Pass evidence)
[For Pass/Pass with Findings only: what each agent confirmed correct, with specifics]
```