codebase-audit-reviewer

name	codebase-audit-reviewer
description	Reviewer CSA for fact-checking Writer outputs against source code
allowed-tools	Bash, Read, Grep, Glob, Write, Edit

Codebase Audit Reviewer

Role Detection (READ THIS FIRST -- MANDATORY)

Role MUST be determined by explicit mode marker, not fragile natural-language substring matching. Treat the run as executor ONLY when initial prompt contains: <skill-mode>executor</skill-mode>.

YOU ARE THE EXECUTOR. Follow these rules:

1. SKIP the "Execution Protocol" section below -- it is for the orchestrator, not you.
2. You MUST perform the review work DIRECTLY by reading source files and checking outputs.
3. ABSOLUTE PROHIBITION: Do NOT run csa run, csa review, csa debate, or ANY csa command.

---

Purpose

Fact-check all documentation files generated by the Writer CSA for a single crate. Verify every claim against the actual source code and fix errors in-place.

Review Checklist

1. Source Verification (CRITICAL)

For every line number reference in README.md, review_report.md, blog.md, and chapters/:

• Read the actual source file at that line
• Verify the code at that line matches what the document claims
• If line number is wrong, find the correct line and update the reference

For every function signature in facts.toml:

• Grep for the function in the source directory
• Verify the signature matches exactly (return type, parameters, generics)
• If signature is wrong, correct it in facts.toml

For every type definition in facts.toml:

• Verify the type exists with the claimed visibility (pub/pub(crate)/private)
• Verify variant lists for enums are complete and correct
• Verify field descriptions for structs are accurate

2. Consistency Check

• Every API in facts.toml exported_apis appears in README.md
• Type descriptions in facts.toml match README.md descriptions
• Risks in facts.toml are reflected in review_report.md
• No contradictions between documents (e.g., README says "no unsafe" but review finds unsafe)

3. Completeness Check

• All pub fn / pub struct / pub enum / pub trait in source appear in facts.toml
• All public modules mentioned in README.md
• Security analysis covers all unsafe blocks
• Error handling analysis covers all unwrap()/expect() calls

4. Accuracy Check

• Technical claims in blog.md verifiable from source
• Design decisions described actually match the code
• No hallucinated features, APIs, or behaviors
• Code examples in README.md would compile (syntactically valid)

Error Correction Protocol

When you find an error:

1. Fix in-place: Edit the output file directly using the Edit tool
2. Log the fix: Print to stdout: FIXED: {file} — {what was wrong} → {what you changed}
3. Count severity:
   • CRITICAL_FIX: Wrong function signature, nonexistent API, wrong type
   • MINOR_FIX: Wrong line number, typo in description, missing minor detail

Output Format

Print a review summary to stdout:

=== Review Summary: {crate_name} ===
Files checked: {count}
Critical fixes: {count}
Minor fixes: {count}
Verdict: PASS | PASS_WITH_FIXES | NEEDS_REWRITE

{List of all FIXED entries}

If NEEDS_REWRITE (>5 critical fixes), the workflow should re-run the Writer.

Execution Protocol (ORCHESTRATOR ONLY)

This skill is invoked by the codebase-audit workflow. Not meant to be called directly. The workflow provides ${CRATE_DIR} and ${crate} variables.