/project-audit

name: project-audit
description: "Project health audit with deterministic scoring. Use when: evaluating project quality, onboarding to new codebase, periodic health checks. Not for: runtime performance analysis, security-specific audits (use /codex-security). Output: 5-dimension score + actionable findings."

Project Audit

When NOT to Use

• Security-specific review (use `/codex-security`)
• Runtime performance profiling
• Mid-development review (use `/codex-review-fast`)

Procedure

1. Run `bash scripts/run-skill.sh project-audit audit.js --json` to collect deterministic scores 2. Parse the JSON output — overall_score, status, dimensions, checks, findings, next_actions 3. **If status = Blocked** (P0 findings) — highlight critical gaps, suggest immediate fixes 4. **If status = Needs Work** (P1 findings) — format improvement roadmap by dimension 5. **If status = Healthy** — summarize strengths, note any P2 improvements 6. Add qualitative interpretation beyond the scores (e.g., "test ratio is good but concentrated in unit tests")

Script Integration

The audit script runs 12 deterministic checks across 5 dimensions:

| Dimension | Checks | What It Measures | |-----------|--------|-----------------| | oss | 2 | LICENSE, README quality | | robustness | 3 | CI config, lint/typecheck, test ratio | | scope | 2 | Declared features vs implementation, AC completion | | runnability | 3 | Package manifest, scripts, env/Docker setup | | stability | 2 | Lock file + audit, type configuration |

Scoring Model

• Each check: `1` (pass) / `0.5` (partial) / `0` (fail) / `N/A` (skipped)
• Dimension score: `applicable_sum / applicable_count * 100`
• Overall score: average of dimension scores
• Confidence: `applicable_checks / total_checks` per dimension

Status Determination

| Status | Condition | Exit Code | |--------|-----------|-----------| | Blocked | Any P0 finding | 2 | | Needs Work | No P0, has P1 | 1 | | Healthy | No P0/P1 | 0 |

Script Failure Fallback

If the script fails, report the error and suggest running manually:

bash scripts/run-skill.sh project-audit audit.js --json

Output Format

## Project Audit Report

| Field | Value |
|-------|-------|
| Repo | [name] |
| Score | **[N]/100** |
| Status | [icon] [status] |

### Dimensions
[table of dimension scores]

### Checks
[list of check results with suggestions]

### Next Actions
[prioritized action items]

## Gate: ✅/⛔

References

• `references/check-catalog.md` — Check definitions, scoring criteria, ecosystem detection (read when investigating a specific check result)
• `references/output-template.md` — Report format examples and JSON schema (read when customizing output)

Verification

• [ ] Script ran successfully
• [ ] All 12 checks executed (or marked N/A with reason)
• [ ] Qualitative interpretation added beyond raw scores
• [ ] Next actions are actionable (include commands where applicable)