codex-skills-library: Skill for Codex

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.