uplift.page
← library
skill🧰 Engineering practicev1 · updated 2026-10-09

Repo Audit

Audits a directory of git repositories and produces an interactive Project Audit — per-repo descriptions, % complete, ratings (market size, value, code quality, security, momentum), bugs by severity, feature suggestions and improvements with type tags, major-change timelines, tech-stack analysis with recommended alternatives, AI model attribution by percent, token usage (commit-block estimates vs measured transcripts with a completeness comparison), total AI thinking time, and a copy-paste improvement prompt per repo. Use when the user asks to audit, review, rate, or take stock of their repos, projects, or portfolio, asks "what's the state of my projects", or wants a project audit for any time window.

Run it as a prompt

Paste this into any AI agent, or fetch it: curl -s https://uplift.page/api/v1/prompts/repo-audit/raw

prompt.md
# Repo Audit

Audit every git repository under a root directory and emit one
`merged.json` conforming to the portfolio-audit data contract
(`references/report-spec.md`). The default renderer is the portfolio-audit
Next.js app (`audits/<date>/merged.json` in that repo); a standalone HTML
fallback is specced in the same reference.

## Hard rules

1. **Read-only toward audited repos.** Git commands limited to
   `log`, `show`, `diff`, `rev-parse`, `ls-files`, `branch -a`. Never build,
   install, checkout, or write inside any audited repo. All output goes to a
   scratch directory and the portfolio-audit repo.
2. **Run the scripts first and trust their inventory.** Worktree dedup, tier
   suggestions, stack detection, secrets flags, model attribution, and token
   math live in `scripts/` — deterministic and testable — not in agent
   judgment. Do not re-derive what they emit.
3. **Every bug and improvement cites a real file** (`path:line` where
   possible). Uncited findings get cut. Defects are reported before praise.
4. **No-churn stack rule.** Recommend a migration only for a concrete payoff
   (cost, blocking limitation, EOL dependency). "Keep as-is" is the expected
   default and is stated explicitly.
5. **Scores come only from `references/rubrics.md` anchors.** Read it before
   scoring. Honest gaps beat invented numbers: missing data is labeled
   "unknown", never guessed.

Install it as a skill

Agents that support the Agent Skills standard load it automatically when it applies.

download
curl -fsSL https://uplift.page/p/repo-audit/SKILL.md --create-dirs -o .agents/skills/repo-audit/SKILL.md
or from any MCP client
MCP server: https://uplift.page/mcp
Tool: pull_skill  {"slug": "repo-audit"}

The full skill

Audit every git repository under a root directory and emit one merged.json conforming to the portfolio-audit data contract (references/report-spec.md). The default renderer is the portfolio-audit Next.js app (audits/<date>/merged.json in that repo); a standalone HTML fallback is specced in the same reference.

Hard rules

  1. Read-only toward audited repos. Git commands limited to log, show, diff, rev-parse, ls-files, branch -a. Never build, install, checkout, or write inside any audited repo. All output goes to a scratch directory and the portfolio-audit repo.
  2. Run the scripts first and trust their inventory. Worktree dedup, tier suggestions, stack detection, secrets flags, model attribution, and token math live in scripts/ — deterministic and testable — not in agent judgment. Do not re-derive what they emit.
  3. Every bug and improvement cites a real file (path:line where possible). Uncited findings get cut. Defects are reported before praise.
  4. No-churn stack rule. Recommend a migration only for a concrete payoff (cost, blocking limitation, EOL dependency). "Keep as-is" is the expected default and is stated explicitly.
  5. Scores come only from references/rubrics.md anchors. Read it before scoring. Honest gaps beat invented numbers: missing data is labeled "unknown", never guessed.

Workflow

  1. Scan. From this skill's directory:
    scripts/scan.sh <root> <since-date>              > scratch/inventory.json
node scripts/attribution.mjs --inventory scratch/inventory.json > scratch/attribution.json
node scripts/tokens.mjs --projects-root <root> --inventory scratch/inventory.json > scratch/tokens.json
    Sanity-check before proceeding: worktrees collapsed into primaries, tier suggestions plausible, block coverage matches spot-checked repos.
  2. Tier the repos (inventory suggests; you may adjust with reason):
    • Tier 1 deep (≥50 commits in window or revenue-touching): read entry points, key modules, recent diffs; 5-8 timeline milestones; ≥3 feature suggestions; 5-10 improvements; real bug hunt in hot files.
    • Tier 2 standard (15-49): manifests + README + main entry; 3-5 milestones; 2-3 features; 3-5 improvements; bugs only if visible.
    • Tier 3 light (<15): manifest + git log; ratings + verdict; 1-2 features. Repos with committed secrets always get a security writeup.
    • Fleet groups: near-identical scaffolds (same template, ~same file count) become ONE entry — audit the shared scaffold once, then a per-repo delta table.
    • Tier 4 legacy (no commits in window, or archived): one compact row — last active, stack, one-liner, one suggestion, verdict archive/revive/harvest. No scores, no bug hunts.
  3. Audit. Parallelize per-repo agents when orchestration is available (each gets the schema + rubrics and returns one record); otherwise go sequentially by tier. Timeline derivation: cluster commits into bursts (>14-day gap starts a new cluster), label each from dominant commit subjects.
  4. Synthesize. Merge records + attribution + tokens into merged.json (contract in references/report-spec.md): portfolio totals, model mix, token series (estimated from commit blocks vs measured from transcripts, with per-repo completeness), AI time, security banner, consolidation notes, methodology + coverage notes.
  5. Verify the numbers before delivering: spot-check commit counts against raw git log, token totals against stats-cache.json, monthly sums against yearly totals, and one repo's block coverage by hand.

Data sources — keep them honest

  • Model attribution comes from === COMMIT SUMMARY === Foundation Model lines, then Co-Authored-By trailers, then bot author emails. Prose mentions of models in commit messages are NOT attribution. Repos without either are "unattributed" — show that bucket.
  • Estimated tokens/AI time come from commit-block Estimated Token Cost / Time Taken lines (full history). Coverage varies by repo (0-100%) — always show block coverage next to estimates.
  • Measured tokens come from agent session transcripts (Claude Code JSONL layout; directory configurable via tokens.mjs --claude-dir), deduped by requestId. Transcript retention is limited — state the earliest surviving timestamp. When the agent keeps a stats cache (stats-cache.json), it provides a longer global daily series (no per-repo split).

Served from the uplift.page library and refreshed within 5 minutes of every update.