checkup

name	checkup
description	Give a repository a full health exam — doc rot, dependency staleness, CI decay, git hygiene, dead links, docs contradicting code — and grade it. Use when the user wants to know what quietly rotted, or a prioritized maintenance list.

Checkup

Repos don't break; they rot — quietly, while everyone works on features. Your job is the annual physical: examine every system, verify empirically instead of assuming, and hand back a graded report where the top three fixes are obvious.

This is a diagnostic, read-only by default. Fix things only when asked; the deliverable is the exam.

The exam

1. Documentation. Every link in README and docs/ actually resolves (check them — don't eyeball). Badges report something true (a build badge for a CI that was deleted is a lie on the front door). Commands in the docs reference scripts and files that still exist. Claims about behavior spot-checked against the code they describe — sample the highest-traffic claims (install, quickstart, config options).

2. Dependencies. Outdated counts by severity (majors behind, years behind), EOL runtimes in engine pins or CI matrices, known advisories, deps that are archived or unmaintained upstream. Distinguish "old but stable" from "old and abandoned."

3. CI and automation. Workflows that fail, are disabled, or haven't run in months; scheduled jobs silently dead; caches pinned to removed tool versions.

4. Git hygiene. Stale branches (merged-but-undeleted vs. abandoned-with-unique-work — the second kind may contain something worth saving; list those separately), time since last release vs. commits accumulated since, tags that drifted from the changelog.

5. Code vitals. TODO/FIXME census with ages (blame the markers — a five-year-old FIXME is a decision, not a task), orphaned files nothing references, config for tools no longer used (the .babelrc after the esbuild migration).

6. Front door. License present and consistent, contributing/security files, issue templates, whether the quickstart actually works — clone-install-run it if cheap enough, and note if this deserves a full literal-execution pass.

Grading

Grade each system A–F with one sentence of evidence, then an overall grade weighted toward what hurts users and contributors first (docs and front door) over internal tidiness. Be calibrated: a B is a fine grade for a living project; reserve D/F for rot that misleads people or will break soon on its own.

The report

Write CHECKUP.md:

1. Vitals table — the six systems, grade each, one-line evidence.
2. Top three — the fixes with the best value-per-effort, each with the concrete action.
3. Findings by system — everything, with file/line/URL specifics so each item is actionable without re-investigation.
4. Quick wins — the sub-five-minute fixes (dead link, stale badge, merged branches) worth batching immediately.
5. Watch list — not-yet-problems trending toward problems (a dep one major behind with a migration guide available now vs. three majors behind next year).

Verify before you accuse: every "dead," "stale," or "contradicts" in the report must come from having checked, not pattern-matched.