Repo Elegance Review
Overview
Evaluate a codebase for elegance by scanning structure, naming, boundaries, and repo hygiene, then deliver a concise verdict with evidence and prioritized improvements.
Workflow
1) Calibrate
- Ask 1-2 quick questions if “pretty/elegant” is undefined: what they value (structure vs. velocity vs. readability), scope (whole repo vs. area), and constraints (stage/team size).
- Proceed with the default rubric if the user does not respond.
2) Quick Scan (lightweight)
- Map the top-level layout with
ls, rg --files, and find . -maxdepth 2 -type d.
- Read
README.md, primary config (package.json, pyproject.toml, etc.), and .gitignore.
- Sample a few key directories; avoid full-depth reads unless asked.
- If it is a git repo, check
git status -s for untracked noise.
3) Assess Against the Rubric
Evaluate each category; collect 1-3 concrete examples per issue with file paths.
- Repo hygiene and clutter (root noise, generated artifacts, ignores not matching reality)
- Information architecture (clear domains, predictable placement, shallow navigation)
- Boundaries and layering (separation of concerns, minimal cross-coupling)
- Naming consistency (directories, modules, types, config alignment)
- Duplication and drift (parallel folders, overlapping responsibilities)
- Dependency and config coherence (single source of truth, minimal duplicative tooling)
- Tests and tooling (test discipline, coverage expectations, docs match behavior)
- Docs and onboarding (README accuracy, quick start reliability, minimal tribal knowledge)
4) Synthesize and Prioritize
- Summarize the top reasons the repo feels elegant or messy.
- Order actions by impact on cognitive load and maintainability.
- Tie each action to its rationale and the evidence that motivated it.
Output Format
Use this structure:
- Verdict:
Pretty / Mixed / Not pretty
- Why: 2-3 bullets with the main reasons
- Strengths: 2-5 bullets
- Issues: bullets formatted as
[Severity] Issue — Evidence (file paths) — Impact
- Actions: numbered list; each item includes the change, why it helps, and where to start (file paths)
- Questions: only if critical uncertainty blocks a confident recommendation
Heuristics
- Favor clarity and predictability over cleverness.
- Minimize cognitive load: fewer places to look, fewer naming variants.
- Prefer cohesive modules and explicit boundaries.
- Keep the root clean; move artifacts to
work/, tmp/, or out/ and align .gitignore.
- Keep docs synchronized with reality; stale docs are anti-elegant.
Pitfalls to Avoid
- Do not nitpick formatting if it does not affect comprehension.
- Do not claim issues without evidence from the repo.
- Do not run heavy commands or full test suites unless the user asks.
1---2name: repo-elegance-review3description: Audit software repositories for elegance/cleanliness/organization and explain why they feel messy or polished. Use when a user asks if a repo is pretty/elegant/clean, wants a codebase aesthetics review, or needs actionable steps to improve structure, naming, cohesion, repo hygiene, or documentation.4---5
6# Repo Elegance Review
7
8## Overview
9
10Evaluate a codebase for elegance by scanning structure, naming, boundaries, and repo hygiene, then deliver a concise verdict with evidence and prioritized improvements.
11
12## Workflow
13
14### 1) Calibrate
15
16- Ask 1-2 quick questions if “pretty/elegant” is undefined: what they value (structure vs. velocity vs. readability), scope (whole repo vs. area), and constraints (stage/team size).
17- Proceed with the default rubric if the user does not respond.
18
19### 2) Quick Scan (lightweight)
20
21- Map the top-level layout with `ls`, `rg --files`, and `find . -maxdepth 2 -type d`.
22- Read `README.md`, primary config (`package.json`, `pyproject.toml`, etc.), and `.gitignore`.
23- Sample a few key directories; avoid full-depth reads unless asked.
24- If it is a git repo, check `git status -s` for untracked noise.
25
26### 3) Assess Against the Rubric
27
28Evaluate each category; collect 1-3 concrete examples per issue with file paths.
29
30- Repo hygiene and clutter (root noise, generated artifacts, ignores not matching reality)
31- Information architecture (clear domains, predictable placement, shallow navigation)
32- Boundaries and layering (separation of concerns, minimal cross-coupling)
33- Naming consistency (directories, modules, types, config alignment)
34- Duplication and drift (parallel folders, overlapping responsibilities)
35- Dependency and config coherence (single source of truth, minimal duplicative tooling)
36- Tests and tooling (test discipline, coverage expectations, docs match behavior)
37- Docs and onboarding (README accuracy, quick start reliability, minimal tribal knowledge)
38
39### 4) Synthesize and Prioritize
40
41- Summarize the top reasons the repo feels elegant or messy.
42- Order actions by impact on cognitive load and maintainability.
43- Tie each action to its rationale and the evidence that motivated it.
44
45## Output Format
46
47Use this structure:
48
49- Verdict: `Pretty` / `Mixed` / `Not pretty`
50- Why: 2-3 bullets with the main reasons
51- Strengths: 2-5 bullets
52- Issues: bullets formatted as `[Severity] Issue — Evidence (file paths) — Impact`
53- Actions: numbered list; each item includes the change, why it helps, and where to start (file paths)
54- Questions: only if critical uncertainty blocks a confident recommendation
55
56## Heuristics
57
58- Favor clarity and predictability over cleverness.
59- Minimize cognitive load: fewer places to look, fewer naming variants.
60- Prefer cohesive modules and explicit boundaries.
61- Keep the root clean; move artifacts to `work/`, `tmp/`, or `out/` and align `.gitignore`.
62- Keep docs synchronized with reality; stale docs are anti-elegant.
63
64## Pitfalls to Avoid
65
66- Do not nitpick formatting if it does not affect comprehension.
67- Do not claim issues without evidence from the repo.
68- Do not run heavy commands or full test suites unless the user asks.
montagao