Release Audit

Release Audit

Overview

Aggregator and router for release readiness: detect what the repo actually ships, dispatch only the matching focused audit skills, and synthesize one scorecard with an ordered ship-blocker list. This is a readiness GATE, not a remediation plan — if the human wants the full audit-to-fix-spec pipeline afterward, route them to nuke-audit.

When to use / when NOT

Use when:

• A human asks whether a project is ready to ship/release/publish/deploy and wants one answer.
• Before a version tag, first npm/PyPI publish, docs launch, or making a repo public.
• The human cannot or does not want to enumerate the individual audit dimensions.

Do NOT use when:

• The question is single-dimension ("is the docs site deployable?") — invoke that focused skill directly (e.g. docs-deploy-readiness).
• The human wants the fixes planned and executed — that is nuke-audit.
• Mid-feature code review — use code-audit or a normal review flow.

How it works

Step 1 — Detect the project's shape (never skip)

Enumerate what the repo contains and ships. Read, do not assume:

1. Root + workspace manifests: package.json (look for workspaces, bin, exports, files, publishConfig, private), pyproject.toml, Cargo.toml, go.mod, etc.
2. CI/deploy config: .github/workflows/, Dockerfile, vercel.json/netlify.toml/fly.toml, release scripts.
3. Docs/content: docs app dirs, *.mdx/markdown content trees, static-site config.
4. Network surfaces: servers, listened ports, auth tokens, webhooks, anything reachable at runtime.
5. UI surfaces: web apps, TUIs, component libraries.

Output a shape table: each shipped surface, its distribution channel (npm package / copy-paste registry / deployed site / installed binary / hosted service), and its audience (end users, developers, internal). Illustrative example only: a monorepo might ship a shadcn-style component registry, an installer CLI, a localhost Hono server, and a docs site — four surfaces, four different bars. Your repo will differ; detect, don't transplant.

Step 2 — Route to dimension skills

Run ONLY the dimensions the shape justifies. Dispatch by name; never re-implement their checklists inline.

Step 3 — Scale the run

Heuristic:

• Single-pass (run each dimension once, directly): ≤2 shipped surfaces, single package, roughly ≤20k LOC.
• Convergence loop (REQUIRED reference: convergence-loop): anything larger — multi-surface monorepos, 3+ dimensions in play, or any repo where one pass cannot hold the whole surface in context. Run the dimensions as parallel agents inside the loop until findings converge.

Step 4 — Synthesize one scorecard

Merge all dimension reports into the Output format below. Ordering rule for blockers: deploy/release-pipeline blockers FIRST (red CI, failing build, broken publish/install) — a red pipeline gates validating everything else — then security/correctness, then public-contract/docs gaps, then polish.

Quality bar

Score each routed dimension 1–5:

Gate rule: overall verdict is NOT READY if any dimension scores ≤2, or if any pipeline blocker exists, regardless of the average.

Output

# Release Audit — <repo>

## Shape detected
| Surface | Channel | Audience |
| ...rows from Step 1... |
Dimensions skipped and why: <e.g. "no docs site → docs-deploy-readiness skipped">

## Scorecard
| Dimension (skill) | Score | Worst findings (file:line) |
| ...one row per routed dimension... |

## Top blockers to ship (ordered)
1. <pipeline/release blocker> — <evidence>
2. ...

## What static analysis could NOT verify — human/runtime must
- Clean-environment build (fresh clone, no caches, pinned toolchain)
- Publish smoke (pack → install in temp dir → import/run)
- Deploy dry-run on the real target
- Live performance under realistic data/load
- Real screen-reader pass (automated a11y checks are not this)
- <anything dimension skills flagged as runtime-only>

## Verdict: READY / NOT READY (+ why)
Next step if NOT READY: run nuke-audit for the full remediation plan.

Common mistakes

• Running every dimension on every repo. A private internal tool needs no handoff-readiness pass; a docs-less library needs no docs-deploy-readiness. Route from the detected shape.
• Hardcoding one project's specifics. Checks like "verify the registry JSON" or "test the --token flag" apply only if Step 1 found that surface.
• Re-implementing focused skills inline. Dispatch handoff-readiness etc. by name; this skill owns routing and synthesis only.
• Burying the red pipeline. A failing build outranks every style finding; order blockers accordingly.
• Declaring READY without the runtime caveats section. Static analysis cannot prove a clean-env install or a screen-reader pass; say so explicitly.
• Drifting into remediation. Findings + verdict only; full fix planning belongs to nuke-audit.
• Referencing sibling skills via @-paths. Name them; @-paths force-load and burn context.