ryderfreeman4logos/codebase-audit-reviewer

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.