Repo health check

Repo Health Check

Find the smallest useful change with the best risk/reward ratio.

Grok Build Mode

• Start in Plan Mode for unfamiliar repos or when changes may touch multiple subsystems.
• Use subagents for parallel read-only discovery when the repo is medium/large:
  • structure: map stack, entry points, and package managers.
  • quality: find test, lint, typecheck, CI, and coverage signals.
  • docs: compare README commands with real config.
  • safety: inspect .gitignore, .grokignore, secrets patterns, hooks, and AGENTS.md.
• Arena-style comparison: if Grok Build exposes Arena Mode, run candidate-first-PR proposals against 3-5 agents and rank by verification confidence. Otherwise simulate by asking subagents for independent candidates.

Workflow

1. Read repo instructions: AGENTS.md, README.md, package/config files, CI files.
2. Identify project type, main runtime, package manager, and quality gates.
3. Look for high-signal risks:
   • stale or missing setup docs;
   • absent tests around core behavior;
   • failing lint/type/test commands;
   • generated output committed unexpectedly;
   • missing .grokignore or obvious secret exposure;
   • dependency and lockfile mismatch;
   • unsafe hooks or unclear agent instructions.
4. Produce 3 candidate PRs ranked by impact, size, blast radius, and verification confidence.
5. Ask for human approval before edits.
6. Implement only the chosen candidate.
7. Run the smallest relevant lint/test/type/docs check.
8. Summarize changed files and residual risks.

Git Discipline

• Never commit generated junk, secrets, or local agent state.
• Keep the first PR tiny.
• If tests fail for unrelated reasons, capture the exact failure and avoid broad cleanup.

Example Prompts

Use repo-health-check. Inspect this repo and propose the smallest safe PR we should ship first. Do not edit yet.

Run repo-health-check with subagents for structure, tests, docs, and safety. Rank the top 3 fixes and wait for my approval.

Output

Start with:

Bottom line: <one sentence>

Then provide:

• repo type and stack;
• discovered commands;
• top risks;
• 3 candidate PRs;
• recommended first PR;
• verification plan;
• whether edits require Plan Mode approval.

Guardrails

• Do not invent test commands. Read package/config files first.
• Do not edit generated files unless the repo intentionally tracks them.
• Do not upgrade dependencies unless explicitly requested.
• If no safe command is available, explain what could not be verified.