Project Recovery Audit
Goal
Determine whether a repository is healthy, degraded, or broken before making changes, and identify the smallest safe next step that restores control.
When to use
Use this skill for inherited repos, stalled projects, broken worktrees, repeated validation failures, or any task where the next action is unclear.
When not to use
Do not use this skill for a small isolated change when the repo shape and affected files are already obvious.
Inputs
- Root
AGENTS.md and any nested agent instructions.
docs/CODEBASE_INDEX.md, docs/CODEX_STATE.md, docs/PLANS.md, and docs/DECISIONS.md.package.json, lockfiles, and top-level folders.- Recent failing logs, CI errors, or user-reported symptoms if available.
- Relevant skills for the task, especially
token-efficient-codex-run and codebase-map-index.
Workflow
- Classify the repo state as healthy, degraded, or broken.
- Identify the source of truth files and the generated files.
- Check for drift between docs, generated outputs, and actual folder structure.
- Identify high-risk areas: validation, secrets, duplicated logic, stale indexes, and large files.
- Decide whether the next step is bootstrap, recovery, targeted fix, or deeper audit.
- If the repo is large or unknown, keep reading minimal and use token-efficient guidance.
- Capture the outcome in state docs and recommend the narrowest safe next action.
Quality bar
- The audit should leave the repo easier to continue from.
- The report should distinguish evidence from inference.
- The first recommended action should be small, safe, and testable.
- If the repo is healthy, say so plainly and avoid unnecessary churn.
Validation
- Run the narrowest useful checks for the files or symptoms involved.
- Run
npm run validate when the repo contract may be stale.
- Run
npm test when helper scripts or parsing logic changed.
- Run
npm run compare:efficiency only when measuring process improvements.
Final response
Report the repo health classification, major risks, the best next action, and the minimal evidence used to make the call.
1---2name: project-recovery-audit3description: Use this when a repository needs a health audit before work starts, especially if the repo may be stale, broken, or hard to resume.4---56# Project Recovery Audit78## Goal910Determine whether a repository is healthy, degraded, or broken before making changes, and identify the smallest safe next step that restores control.1112## When to use1314Use this skill for inherited repos, stalled projects, broken worktrees, repeated validation failures, or any task where the next action is unclear.1516## When not to use1718Do not use this skill for a small isolated change when the repo shape and affected files are already obvious.1920## Inputs2122- Root `AGENTS.md` and any nested agent instructions.23- `docs/CODEBASE_INDEX.md`, `docs/CODEX_STATE.md`, `docs/PLANS.md`, and `docs/DECISIONS.md`.24- `package.json`, lockfiles, and top-level folders.25- Recent failing logs, CI errors, or user-reported symptoms if available.26- Relevant skills for the task, especially `token-efficient-codex-run` and `codebase-map-index`.2728## Workflow29301. Classify the repo state as healthy, degraded, or broken.312. Identify the source of truth files and the generated files.323. Check for drift between docs, generated outputs, and actual folder structure.334. Identify high-risk areas: validation, secrets, duplicated logic, stale indexes, and large files.345. Decide whether the next step is bootstrap, recovery, targeted fix, or deeper audit.356. If the repo is large or unknown, keep reading minimal and use token-efficient guidance.367. Capture the outcome in state docs and recommend the narrowest safe next action.3738## Quality bar3940- The audit should leave the repo easier to continue from.41- The report should distinguish evidence from inference.42- The first recommended action should be small, safe, and testable.43- If the repo is healthy, say so plainly and avoid unnecessary churn.4445## Validation4647- Run the narrowest useful checks for the files or symptoms involved.48- Run `npm run validate` when the repo contract may be stale.49- Run `npm test` when helper scripts or parsing logic changed.50- Run `npm run compare:efficiency` only when measuring process improvements.5152## Final response5354Report the repo health classification, major risks, the best next action, and the minimal evidence used to make the call.
YankielDBC2