# Project Recovery Audit

> Use this when a repository needs a health audit before work starts, especially if the repo may be stale, broken, or hard to resume.

- Skill: `yankieldbc2/project-recovery-audit` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add yankieldbc2/project-recovery-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yankieldbc2/project-recovery-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: YankielDBC2 (https://skillmd.com/u/yankieldbc2)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/yankieldbc2/project-recovery-audit

---


# 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

1. Classify the repo state as healthy, degraded, or broken.
2. Identify the source of truth files and the generated files.
3. Check for drift between docs, generated outputs, and actual folder structure.
4. Identify high-risk areas: validation, secrets, duplicated logic, stale indexes, and large files.
5. Decide whether the next step is bootstrap, recovery, targeted fix, or deeper audit.
6. If the repo is large or unknown, keep reading minimal and use token-efficient guidance.
7. 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.