read-and-review

Read and Review

When to use

The user shares an external reference (RFD, paper, blog post, library docs, postmortem) and wants its lessons applied to the codebase. The reference contains principles that may reveal latent bugs, missing documentation, or anti-patterns in existing code.

Workflow

1. Read and extract rules

Read the reference thoroughly. Extract a numbered list of concrete, testable rules. Each rule should be:

• Falsifiable: you can check whether code violates it
• Scoped: applies to a specific pattern, not "write good code"
• Actionable: a violation has a known fix

Example from Oxide RFD 397:

1. Never hold tokio::sync::Mutex across .await
2. Document cancellation-safety contracts on async functions
3. tokio::time::timeout does not cancel the server, only the client
4. try_join! cancels remaining futures when any one fails

2. Dispatch audit subagents

Send parallel subagents to search the codebase for violations:

• Code reviewer subagent: review recently changed files against the extracted rules. Report findings with severity levels.
• Explorer subagent: search the broader codebase for the specific patterns the rules warn about (e.g., tokio::sync::Mutex, tokio::select!, try_join!). Report each occurrence with file path, line numbers, and whether it's safe or a violation.

3. Triage findings

Classify each finding:

• Must fix: violates the rule and can cause data corruption, state desync, or silent failure
• Should fix: violates the rule but impact is bounded (e.g., test flakiness, misleading error variant)
• Document: the code is correct but the reason it's safe is not obvious; add a comment explaining why
• Not applicable: the pattern is present but the rule doesn't apply (e.g., timeout around a stateless probe is fine)

4. Fix violations

Fix must-fix and should-fix items. For each fix:

• Make the minimal change that resolves the violation
• Add or update documentation explaining the safety argument
• Run tests to confirm no regressions