Dhpk Project Audit

---
name: dhpk-project-audit
argument-hint: '[--dir <path>]'
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 /dhpk:change-verdict --mode security). Output: 5-dimension score + actionable findings.'
metadata:
  dhpk-invocation-class: implicit-eligible
---

# Project Audit

`$SKILL_DIR` denotes the physical directory containing the selected `SKILL.md`;
it is path notation, not an ambient environment variable or repository-root
lookup. Resolve it before running the audit from an arbitrary consumer cwd.

## When NOT to Use

- Security-specific review (use `/dhpk:change-verdict --mode security`)
- Runtime performance profiling
- Mid-development review (use `/dhpk:change-verdict --mode code`)

## Procedure

1. Run `node "$SKILL_DIR/scripts/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
node "$SKILL_DIR/scripts/audit.js" --json
```

## Output

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