AI-Legibility Repo Assessment — Agent Prompt

gistfile1.txt

You are assessing this repository for "AI-legibility": how readily an AI coding
agent can understand it and make safe, correct changes WITHOUT tribal knowledge.

RULES
- Work only from what is present in the repo. Where critical knowledge appears to
  live outside it (heads, external docs, convention-by-habit), flag it as a gap —
  do not guess or fill it in.
- Be terse. This is a scannable assessment, not an essay. Obey the length caps
  below exactly. No preamble, no restating these instructions, no filler.
- On a large repo, do NOT read everything. Read entry points, config/build files,
  and 2–3 representative module slices. Say what you sampled in one line.

FIRST, confirm the repo is workable:
- Can it be built/run and can tests execute from a clean checkout using only
  repo-visible instructions? If not, note the first blocker. (A repo an agent
  can't stand up is hostile regardless of the scores below.)

SCORE these seven dimensions, 1 (hostile) – 10 (legible). Anchor bands — use the
full range, do not cluster at 6–8:
  1–2  hostile: an agent will confidently do the wrong thing here.
  3–4  poor: usable only with heavy human guardrails.
  5–6  mixed: agent can work but must guess on non-trivial changes.
  7–8  good: agent handles most changes safely from repo-visible info.
  9–10 legible: agent operates as a well-informed senior would.
Reserve 9–10 for genuinely exemplary; if you can name a real gap, cap at 8.
1. STRUCTURAL CONSISTENCY — predictable layout; module boundaries match domains;
   similar things in similar places; no competing structures / organic sprawl.
2. CONVENTION EXPLICITNESS — linter/formatter/style configs committed & enforced;
   CONTRIBUTING or equivalent; conventions machine-readable vs. inferred; one way
   to do a given thing vs. many.
3. TYPE & INTERFACE CLARITY — typed signatures vs. any/loose dicts; explicit public
   contracts; changes verifiable against types vs. runtime guessing.
4. TEST COVERAGE & QUALITY — tests exist, run, pass from clean checkout; act as
   executable spec (express intent); fast self-check loop; critical-path vs.
   happy-path only.
5. DOCUMENTATION CURRENCY — README explains setup/architecture/intent; docs current
   vs. stale-and-confidently-wrong (stale is WORSE than absent — call it out);
   non-obvious behavior ("don't touch X before Y") documented anywhere.
6. COUPLING VISIBILITY — change blast-radius inferable from code vs. hidden;
   undocumented cross-module / cross-repo deps; dead code, abandoned patterns,
   vendored/generated files polluting signal (agent can't tell fossils from live).
7. AGENT AFFORDANCES — agent-facing guidance present & accurate (CLAUDE.md /
   AGENTS.md / .cursorrules, task runners, documented commands that actually
   match reality); CI / hooks / type-check that give an agent feedback when it
   breaks something.

OUTPUT — in this order, nothing else:

A. SUMMARY TABLE (this is the primary deliverable):
   | Dimension | Score (/10) | Highest-impact fix (≤12 words) |
   Plus a Buildable row (Yes/No + blocker) and an OVERALL row
   (average /10 + one of: agent-ready / usable with caution / remediate first).

B. TOP 3 REMEDIATIONS — ranked by impact ÷ effort. One line each:
   "<fix> — <concrete first action>". No paragraphs.

C. HOSTILE HOTSPOTS — up to 3 bullets. Each: file/area + why an agent would make
   a confident wrong change there. ≤20 words each.

D. ONBOARDING TEST — name one realistic change (e.g. "add a field to entity X").
   In ≤4 sentences: could an agent do it safely from repo-visible info alone, and
   where must it guess?

Each dimension justification lives ONLY as the fix cell in the table. Do not write
per-dimension prose sections. Total output target: under one screen.