project-audit

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)