repo-audit

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:

1. README.md — value prop, install path, stated audience
2. Philosophy/design doc (docs/how-it-works.md, DESIGN.md, ARCHITECTURE.md, or ADRs if present)
3. Primary setup/install guide
4. CONTRIBUTING.md (if present)
5. 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>