| name | repo-audit |
| description | Audit a repo across four dimensions — uniqueness and selling point, philosophy-to-implementation coherence, setup and doc effectiveness, and codebase quality (DRY, KISS, SRP, composition). Invoke when asked to review, assess, or health-check a repo. |
| category | agent-ops |
| tags | ["audit","analysis","sdlc","docs","philosophy"] |
| hidden | true |
Repo Audit
A four-dimension analysis. Run from any project directory — the audit reads the repo under analysis, not canon. Produces an inline report and always writes or updates the latest report at critique/canon-critique.md in the repo under analysis, with the audit run DateTime as the first line.
Before Auditing
Read these in order, stop when you have enough to answer each dimension:
README.md — value prop, install path, stated audience- Philosophy/design doc (
docs/how-it-works.md, DESIGN.md, ARCHITECTURE.md, or ADRs if present)
- Primary setup/install guide
CONTRIBUTING.md (if present)- 3–5 core source files (main CLI entrypoint, core logic) — skip test fixtures, generated files,
node_modules, dist
Do not read everything. Read until you can answer the questions for each dimension.
Dimension 1 — Uniqueness and Selling Point
Goal: Determine whether the repo has a clear, genuine differentiator — and whether it lands for the target user.
Questions to answer:
- What is the stated purpose? Who is the target user?
- What problem does it solve, and for whom?
- What alternatives exist? Name them. What does this repo do that they don't?
- What is genuinely novel vs. table stakes?
- Does the README earn its differentiation claim, or does it assert without showing?
- Would the target user read this and say "finally" — or "so what"?
Rate: Distinct / Murky / Generic
Dimension 2 — Philosophy-to-Implementation Coherence
Goal: Verify the implementation honors the philosophy — not just in words, but in every command, tool, and convention.
Questions to answer:
- What is the repo's stated philosophy? Extract it explicitly from the docs. If no dedicated philosophy doc exists (no
DESIGN.md, ARCHITECTURE.md, docs/how-it-works.md, or ADRs), extract from README.md instead — and note the absence as a finding. The missing doc is a finding, not a stop condition; proceed with best-effort ratings for all four dimensions.
- Does the implementation honor it? Check: command surface size, complexity vs. claimed simplicity, patterns in core code
- Does the usage pattern (workflows, commands, default behaviors) reflect the philosophy?
- Where does the implementation contradict or silently undermine the stated philosophy?
- Are there features that have crept in and violated it?
- If the README's stated feature count or command surface contradicts the actual implementation, flag it here as a coherence failure (and also in Dimension 1 as a positioning gap).
Look for: philosophy stated but not implemented, implementation that outgrew its stated scope, or a tool that claims minimalism but adds flags for every edge case.
Rate: Strong / Drifting / Contradicted
Dimension 3 — Setup and Doc Effectiveness
Goal: "Can a newcomer get from zero to working using these docs?" Focus on the user journey, not per-claim accuracy. (Per-claim accuracy → doc-audit.)
Questions to answer:
- Is there a clear, tested install path? Can you follow it cold, without prior knowledge?
- Are prerequisites explicit before they're needed — not buried mid-guide?
- Is the first success moment reachable without hitting a wall? How many steps?
- Do examples exist? Do they match current behavior?
- Is the docs structure navigable? Can you find what you need without reading everything?
- Are there implicit environment assumptions (OS, shell, global tools)?
- When step N fails, is there a recovery path — or does the guide end there?
Rate: Clear / Gaps / Broken
Dimension 4 — Codebase Quality
Goal: Assess how well the codebase follows SDLC principles adapted for the repo's paradigm (shell, markdown, CLI, agents — not OOP).
Principles to apply (map to what's present, skip what isn't applicable):
| Principle | In shell/CLI/agent context |
|---|
| SRP (Single Responsibility) | Each script/tool/skill does one thing; no file with multiple unrelated jobs |
| DRY (Don't Repeat Yourself) | Each fact has one canonical location; logic isn't duplicated across scripts |
| KISS (Keep It Simple) | Scripts are as simple as they could be; no abstractions that could be a one-liner |
| YAGNI (You Ain't Gonna Need It) | No unused flags, config options, or features not yet needed |
| Composition over commands | Complex operations built from smaller composable units, not monolithic multi-step scripts |
| CoC (Convention over Configuration) | Conventions established and followed; explicit config only where necessary. For canon-managed content markers in shared files (AGENTS.md, HANDOFF.md, etc.): new markers should follow <!-- canon:<name>:BEGIN/END --> (see standards/skill-setup-std.md); flag any new ad-hoc marker naming that doesn't follow it. AI-SKILLS/MODEL-TIERS are documented exceptions predating the convention — not a violation. |
| Separation of concerns | Config vs. logic, data vs. behavior, CLI vs. agent, state vs. judgment — each in its place |
| Context efficiency (AI-native repos) | Always-loaded files are lean; skills have tight activation; no content duplication across imports. In skill files specifically: no summary: frontmatter field when description: already covers it; no --- horizontal rules (visual noise in injected context); no step that duplicates another step's outcome |
Questions to answer:
- Find the 3 most significant violations. Name them as
file:line: problem. fix.
- Is there structural complexity that compounds failure (shared mutable state, side-effects in unexpected places)?
- Does the complexity of the codebase match the complexity of the problem it solves?
- Is the separation of concerns clean, or do concerns bleed into each other?
Rate: Clean / Acceptable / Needs Work
Report Format
Use this structure exactly. Omit sections that aren't applicable. After composing the report, ensure critique/ exists and write the same report to critique/canon-critique.md, replacing the prior contents so the file is the latest critique snapshot.
The first line must always be the local DateTime when the audit ran, formatted as MM-DD-YYYY hh:mm AM/PM:
Audit run: MM-DD-YYYY hh:mm AM/PM
Audit run: MM-DD-YYYY hh:mm AM/PM
## Repo Audit: <repo-name>
### 1. Uniqueness / Selling Point — [Distinct | Murky | Generic]
- <finding>
- <finding>
Recommendation: <one actionable sentence>
### 2. Philosophy Coherence — [Strong | Drifting | Contradicted]
Stated philosophy: <extract — quote or paraphrase from source file>
- <specific example of coherence or drift>
- <specific example of coherence or drift>
Recommendation: <one actionable sentence>
### 3. Docs Effectiveness — [Clear | Gaps | Broken]
Zero-to-working: <yes/no + rough step count or time estimate>
- <specific friction point or win>
- <specific friction point or win>
Recommendation: <one actionable sentence>
Note: per-claim accuracy → run doc-audit
### 4. Codebase Quality — [Clean | Acceptable | Needs Work]
- file:line: problem. fix.
- file:line: problem. fix.
- file:line: problem. fix.
Recommendation: <one actionable sentence>
### Summary
Overall: [Healthy | Minor gaps | Needs attention]
Top priority: <the one thing to address first, and why>
