audit-reviewability

Audit and repair code, comments, documentation, and tests for reviewability debt.

8|6|Updated Jul 31, 2026
One-click install
npx skills add https://github.com/stellar-experimental/stellar-raven --skill audit-reviewability-stellar-experimental
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: audit-reviewability
Source: https://github.com/stellar-experimental/stellar-raven/tree/main/.agents/skills/audit-reviewability
Command: npx skills add https://github.com/stellar-experimental/stellar-raven --skill audit-reviewability-stellar-experimental

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? AI-generated and rapidly iterated codebases accumulate reviewability debt: stale comments, duplicated documentation, speculative compatibility paths, diff narratives, and tests that mirror implementations. This Skill audits and repairs those artifacts so human reviewers can understand and verify changes without trusting unverified summaries. ## Core Features & Use Cases - Audit and repair modes: Inspect and report findings without editing, or audit, edit, and verify when asked to clean or fix. - Rubric-based classification: Apply truth, durability, signal, locality, proportion, scope, verification, and preservation gates from references/audit-rubric.md, with severity-ranked findings. - Preservation-first repair: Fix false contracts, remove dead paths and speculative compatibility, consolidate duplicated docs, and replace implementation-mirroring tests while protecting human edits and durable knowledge. - Use Case: After a large AI-generated pull request, run the skill against the diff to prune transient narratives, stale comments, and redundant tests, then verify the final diff is smaller to understand than the problem it solves. ## Quick Start Use the audit-reviewability skill to audit this pull request for reviewability debt and repair the findings.

Frequently Asked Questions about audit-reviewability

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clean up AI-generated code before code review?

Run the skill in repair mode against the change's fixed point. It audits the full diff, classifies findings with the reviewability rubric, repairs false contracts, dead paths, and redundant comments in risk order, then verifies with the repository's test commands.

What is reviewability debt in a codebase?

Reviewability debt is any artifact that consumes reviewer attention without durable value: stale comments, diff narratives, duplicated documentation, speculative compatibility layers, and tests that mirror implementations. The skill classifies these using truth, durability, signal, and proportion gates.

Can I audit a change without modifying the repository?

Yes. Audit mode inspects and reports findings with severity, evidence, and smallest valid repair, leaving the repository unchanged. Repair mode additionally edits and verifies, and is used when the request asks to clean, fix, prune, or simplify.

Does the audit remove all comments from my code?

No. The rubric is preservation-first: comments carrying public contracts, invariants, safety constraints, domain reasons, or surprising behavior are kept. Only comments that restate code, describe the diff, or are stale and contradicted by tests are removed.

When should I not use a reviewability audit?

Avoid it when compatibility paths have supported consumers or released public contracts, since removal requires evidence from repository policy, deployed clients, and migration commitments. Uncertain cases are recorded as risks rather than silently deleted.