nih-audit

Files (3)

• SKILL.md
• categories.md · references/
• finding-template.md · references/

SKILL.md (first lines)

# NIH Audit — Not Invented Here

Find code reinventing the wheel. Recommend libraries. Score with evidence.

`/nih-audit [scope]` — `scope` defaults to repo root.

## Phase 0 — Manifest discovery (no LLM)

Find dependency manifests anywhere in scope, excluding `node_modules/`,
`vendor/`, `.git/`, build artefacts:

- `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Gemfile`,
  `requirements.txt`, `composer.json`, `build.gradle`, `pom.xml`, `mix.exs`.

Extract dependency names per ecosystem:

| Manifest | Extract |
|----------|---------|
| `package.json` | `jq -r '(.dependencies + .devDependencies) // {} \| keys[]'` |
| `Cargo.toml` | parse `[dependencies]` table |
| `pyproject.toml` | `[project.dependencies]` or `[tool.poetry.dependencies]` |
| `go.mod` | `require` block module paths |
| `requirements.txt` | line-by-line package names |

Build a `depManifest`:

```json
{
  "workspaces": [
    { "root": ".", "ecosystem": "node", "deps": ["express", "zod"] }
  ],
  "primaryLanguages": ["typescript"]
}
```

If no manifest is found anywhere in scope, abort with a clear message —
without an installed-deps list there is nothing to cross-reference.

## Phase 1 — Structural NIH scan

Spawn the `nih-scanner` sub-agent:

```
inputs:
  languages   = primaryLanguages from Phase 0
  scope       = $ARGUMENTS or repo root
  depManifest = JSON from Phase 0
  slug        = <derived slug>
```

The scanner returns a JSON candidate list inline plus a one-paragraph
summary. Parse the candidates from the response. If 0 candidates, report
clean and stop.

## Phase 2 — Library discovery (parallel, /research)

Group candidates by `category` (RETRY, UUID, VALIDATION, DATE, DEBOUNCE,
CLONE, ARGPARSE, STRING, HTTP, SERIALIZATION, ERROR, CRYPTO, SECURITY,
FORMAT, COMPARE).

For each category, dispatch `/research` with a focused question shape:

```
/research "best <category> library for <language>; must be MIT/Apache/BSD;
list weekly downloads or crates.io downloads, GitHub stars, last commit
date, contributor count; flag if functionality is in the standard library"
```

Cap: max 5 parallel research dispatches. If `/research` is unavailable,
emit candidates with `recommendation: null` and a note.

For each library returned, capture:

- name + latest version
- license (flag GPL; prefer MIT/Apache-2.0/BSD)
- weekly/monthly download count
- GitHub stars, last commit date, contributor count
- whether it is stdlib, micro-library, or framework
- one-sentence API example showing replacement shape

Drop recommendations whose name is already in `depManifest`. Stdlib
alternatives (no new dep) are the highest-value class — keep them
prioritized.

See `references/categories.md` for the canonical category-to-library map.

## Phase 3 — Spec and intent alignment

Find spec directories within scope: `**/specs/*.md`, `.cheese/specs/*.md`.
Filter out `node_modules/`, `vendor/`, `.git/`.

For each candidate, look for signals that the NIH choice was deliberate:

- **In specs**: keywords like "intentionally", "we chose to build", "build
  vs buy", "don't use", "avoid dependency on" near the candidate's concept.
- **In the candidate file**: comments like `intentionally`, `deliberately`,
  `we chose`, `NOTE:`, `DECISION:`, `instead of`, `rather than`.

Apply scoring modifiers:

| Signal | Modifier |
|--------|----------|
| Spec explicitly chose NIH | -30 |
| Code comment explains NIH choice | -20 |
| Library covers planned spec features | +10 |

## Phase 4a — Score

For every candidate with a library recommendation, run the 4-step
confidence chain:

### Step 1 — classify finding type

| Type | Base | Cap |
|------|------|-----|
| `REPLACE_WITH_STDLIB` | 55 | 100 |
| `REPLACE_WITH_MICRO_LIB` | 45 | 95 |
| `REPLACE_WITH_FRAMEWORK` | 35 | 85 |
| `EXTRACT_TO_EXISTING_DEP` | 50 | 95 |

From paulnsorensen/cheese-flow, MIT.

More from paulnsorensen/cheese-flow