readiness-audit

name	readiness-audit
description	Audit whether a surface is clean, legal, and consistent enough for a named event such as release, public flip, or handover. Runs read-only exploration, controller re-verifies each load-bearing claim, tiers findings, creates phased remediation with owners, records gates, and emits an end-to-end verification recipe. Recurring sibling of /foundational-review; no irreversible-decision anchor required.
argument-hint	<scope-root> [--for "<event: release|public-flip|handover|…>"]
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch, Skill, Task

/readiness-audit — "Is it clean / legal / consistent to ship?"

A checklist-against-a-surface audit that recurs, needs no irreversible-decision anchor, and answers "is it ready to ship for THIS event," not "should this shape exist." The companion format is canonicalized in the "Companion format: the readiness audit" section of the foundational review chain process doc (read at Step 1).

This skill is orchestration + artifact templates only. The format spec and the pairing contract live in the canonical process doc, which Step 1 reads. Do not reproduce them from memory.

Sibling of /foundational-review — audit = recurring, checklist-shaped, surface-anchored; chain = per-decision, verdict-shaped. When the event is a SHIP / FREEZE / PUBLIC-FLIP, the pairing contract says run BOTH: this audit for the surface, the chain for the decision (audit first — cheaper, produces the evidence base). Step 8 surfaces that pairing.

When to use

• Before a release, a public-repo flip, a handover, or any "is this ready for X" moment that's about the surface (clean, legal, consistent), not the shape.
• As the recurring instrument — re-runnable whenever the surface changes; no decision anchor needed.

If the question is "should this shape exist / is this the right thing built the right way" before an expensive-to-undo step → use /foundational-review. If it's a plan about to execute → /prospect.

Step 0: Inputs

Parse <scope-root> (first positional) and --for "<event>". If thin, collect interactively:

Inputs:
  Scope root:   <path under audit>
  Ready for WHAT:  <the event: public release | repo public-flip | handover | v1.0 tag | …>
  Locked decisions:  <any already-decided constraints that become audit premises>
  Inherited audits:  <prior audits whose findings/claims this one re-derives, never trusts>

"Ready for WHAT" is the frame that makes a finding a blocker vs. a nice-to-have — get it explicit before exploring.

Step 1: Load Canonical Companion Format & Bound Scope

1. Read the "Companion format: the readiness audit" section of the canonical process doc, preferring a user copy when present:

   • If <knowledge_folder>/approaches/foundational-review-chain.md exists (resolve <knowledge_folder> from ~/.claude/aria-knowledge.local.md), read THAT.
   • Otherwise read the plugin-bundled copy at ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/foundational-review/foundational-review-chain.md (always present).

   It defines the tier structure, the agent-claim-correction discipline, and the composition contract with the chain.

2. State in-scope / out-of-scope explicitly. Fence sibling workstreams ("the chain's plan owns architecture-freeze risks — not duplicated here").

Step 2: Parallel Exploration (read-only)

Dispatch exploration agents per surface — typically:

• source/build — what builds, what's dead, what the artifact actually contains
• licensing/hygiene — license headers, secrets, internal URLs, third-party-asset rights
• docs/tooling — stale docs, broken references, release pipeline presence
• over-build (opt-in: when --for mentions bloat/over-engineering, or always when the scope is a code repo) — one read-only Explore agent walks rules/overbuild-patterns.md's ladder + smells across the surface's source, reporting candidate over-build sites (each: file:line, matched smell, failed ladder rung, concrete leaner alternative). Respects aria:simplification markers — a marked site is reported "resolved", never flagged. Read-only per the guardrail below: it reports what it would change, never mutates a build artifact.

Use the Task tool (Explore agent type) per surface, in parallel. Guardrail — read-only verification probes only. No probe may mutate a build artifact. (A real incident: an agent "verified a build" by RUNNING it and overwrote a generated source file.) If a check would require building/running, the agent reports what it would run + expected output, and the controller decides whether to run it under the diff-check discipline in Step 3.

Step 3: Controller Re-Verification (the defining discipline)

This is what separates a readiness audit from a pile of agent claims. Re-verify every load-bearing agent claim with a direct controller-level check before it enters the findings. In real runs, multiple agent claims were corrected by direct checks.

For each claim an agent surfaced:

• Re-derive it yourself (Read/Grep/git), at file:line.
• If it holds → it becomes a finding with a verified Evidence cell.
• If it's wrong → record the correction as a decision-trail row: Agent claimed X → direct check showed Y → corrected.
• Inherited claims from prior audits are re-derived, never trusted (per the composition contract — a real review corrected an inherited file misattribution and a mis-scoped variable claim).

Artifact diff-check (mandatory). If any verification required building or running anything, immediately run git diff --stat (and restore) to prove no tracked artifact was mutated. Record the diff-check result in the audit. A test-build step that can't show a clean diff is a finding against the audit itself.

Step 4: Tiered Findings

Each finding carries a verified Evidence cell (citation from Step 3, not an agent assertion):

## Tier 0 — Blockers (must fix before the event)
| # | Finding | Evidence (file:line / probe result) | Owner |
## High
## Medium
## Low (hygiene)

The tier is set by the "ready for WHAT" frame from Step 0 — a stale internal URL is Tier 0 for a public flip, Low for an internal handover.

Step 5: Conceptual Observations (no code change)

Observations worth recording that don't propose a code change — design smells, future risks, "we should decide X someday." Kept separate from findings so the remediation plan stays actionable.

Step 6: Phased Remediation Plan

Findings are NOT a shipping list (cite audit-findings-as-shipping-list-without-triage). Triage them into phases with owners:

## Remediation Plan
Phase 1 (pre-event): <Tier 0 + the High items that block the event> — owners
Phase 2 (fast-follow): <remaining High + Medium> — owners
Phase 3 (backlog): <Low / hygiene> — owners

One owner per item. If the chain (/foundational-review) is also running, fence by reference: each item has exactly one owning document.

Step 7: End-to-End Verification Recipe

The exact sequence to prove the surface is ready after remediation — the commands/checks + expected output a cold executor runs to confirm. This is the audit's definition-of-done.

Step 8: Gates & Pairing

• Gates — for genuine decisions, surface via AskUserQuestion: the decision, the options, the consequence of each. Don't bake a default for a real decision.
• Pairing — if the event is a SHIP / FREEZE / PUBLIC-FLIP, note that the pairing contract recommends running /foundational-review --decision "<event>" on the decision, with this audit's verified findings as admissible evidence and its locked decisions as review premises. Gates from both should land in ONE gate table (the chain's spec) so nothing ships on a gate answered in only one document.

Step 9: Output & Commit

• Write <scope-root>/…/audit-<YYYY-MM-DD>-<event>-readiness.md (match the project's docs convention for the location).
• Commit local (named path, no push). If Bash/git is unavailable, emit a copy-paste commit message.
• Suggest aria intake entries (insights / decisions) per the standard confirmation flow.

Step 10: Validation Gates

Before declaring the audit complete, verify:

1. "Ready for WHAT" stated and used to set tier severity.
2. Every finding has a verified Evidence cell sourced at Step 3, not an unverified agent claim.
3. Controller re-verification ran — agent claims re-derived; corrections recorded as a decision trail.
4. Artifact diff-check recorded if any verification built/ran anything (git diff --stat clean + restore).
5. Inherited claims re-derived, never trusted from a prior audit.
6. Findings tiered, not flat; remediation is PHASED with one owner per item (not a shipping list).
7. End-to-end verification recipe present.
8. Real decisions surfaced as gates (AskUserQuestion), no fabricated defaults.
9. Pairing surfaced if the event is a ship/freeze/flip.
10. Report committed (named path, no push).

If any check fails, self-correct once; if it can't be closed, surface the gap explicitly.