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.

1. Produce 3 candidate PRs ranked by impact, size, blast radius, and verification confidence.
2. Ask for human approval before edits.
3. Implement only the chosen candidate.
4. Run the smallest relevant lint/test/type/docs check.
5. 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: 

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DominikTobureto
• Source: DominikTobureto/awesome-grok-build
• License: MIT

Install and usage instructions live in the source repository linked above.