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
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)