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 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: "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]