audit

Audit

Use this skill when the user wants an adversarial methodology review of a code change. The skill builds a structured prompt from the plugin's methodology and routes it to Codex through codex-plugin-cc.

This skill does not run the audit itself. It assembles context, then hands off to Codex. Codex does the actual review.

Do not autoload — only respond when the user invokes /chipdev-method:audit or matches the trigger phrases in the description.

---

Prerequisites

The user must have:

1. codex CLI installed and on PATH.
2. codex-plugin-cc installed (see https://github.com/openai/codex-plugin-cc).
3. The current working directory must be a git repository.

If any prerequisite is missing, surface a clear remediation step before proceeding.

---

How to use this skill in a response

When triggered, perform the following steps in order:

Step 1. Verify prerequisites

command -v codex >/dev/null || echo "MISSING: codex CLI"
git rev-parse --is-inside-work-tree >/dev/null 2>&1 || echo "MISSING: not a git repo"

If codex is missing, instruct the user to install codex-plugin-cc and ensure codex is on PATH. Stop.

If not in a git repo, tell the user to invoke audit from the project's git working tree. Stop.

Step 2. Resolve the audit target

Default target: the current diff against main (or master).

If the user passed an argument:

• A path → audit only files under that path.
• A git ref (e.g., HEAD~3) → audit the diff between that ref and HEAD.
• A git range (e.g., main..feature/foo) → audit that range.

Ask the user to confirm the resolved target before proceeding.

Step 3. Collect change context

Gather, in order:

1. The textual diff (git diff <range>) — capped at ~2000 lines; if larger, summarize per-file change counts and ask the user to narrow.
2. The list of files changed.
3. The latest commit message(s) on the range.

Step 4. Build the audit prompt

Use the checklist in references/audit-checklist.md as the audit rubric. Build a structured prompt for Codex with:

1. The plugin's six invariants (verbatim from INDEX.md).
2. The four contract types (verbatim from define-contracts).
3. The audit rubric items.
4. The change context (diff + commit messages).
5. The expected output format (per-violation: principle → file:line → evidence → severity → recommended fix).

Save the prompt to a temporary file in .humanize/skill/<id>/audit-prompt.md or pipe directly. Either way, do not put a multi-thousand-line diff into a single shell argument.

Step 5. Invoke Codex

Recommended invocation, via the codex-plugin-cc shipped command:

# Through the codex-plugin-cc /codex:adversarial-review command,
# which the user must have installed.
# Equivalent direct codex call:
codex exec -m gpt-5.4 \
  -c model_reasoning_effort=high \
  --full-auto \
  -C "$(git rev-parse --show-toplevel)" \
  - < "$AUDIT_PROMPT_FILE"

If codex-plugin-cc exposes a slash command (e.g., /codex:adversarial-review), prefer using it through the parent Claude Code session rather than calling codex exec directly — that gives the user the standard codex result-handling UX.

Step 6. Format the result

When Codex returns:

1. Group findings by severity (Critical / High / Medium / Low / Info).
2. For each finding, show:
   • Principle violated (one of the six invariants, or a contract type).
   • Location (file:line).
   • Evidence (a short quote from the diff).
   • Recommended fix (one sentence).
3. End with a summary count and a recommended action (block / fix-then-merge / acknowledge / no-action).

Do not restate the entire Codex output verbatim. Compress.

If Codex returned a clean review (no violations), say so plainly with the review's confidence note.

---

What this skill audits [abstract]

The audit covers, in order of priority:

1. The six invariants. Generation-over-hand-writing, contract-over- convention, composition-over-inheritance, configuration-over-hard-coding, sparse-over-preallocated, determinism-over-concurrency.
2. Contract integrity. Are interface definitions in the DSL? Are protocol annotations explicit? Is the state contract documented?
3. Observability. Does new module code expose the probe interface?
4. Lint posture (RTL). Are new lint violations introduced?
5. Difftest readiness. If the change touches behavior model or RTL, are probes consistent on both sides?

The full rubric is in references/audit-checklist.md.

---

Common failure modes when running an audit [abstract]

• Diff is too large. Codex gives a generic review. Narrow to a single module, or audit per-file in batches.
• No commit messages. Codex has no intent context; reviews are unfocused. Ask the user for a 1-paragraph intent before invoking.
• Audit run on generated code. Code emitted from the DSL toolchain shouldn't be hand-edited and shouldn't trigger violations. Filter build/ or generator outputs out before invoking.
• Audit treated as merge gate without a recourse process. Codex is a reviewer, not an oracle. Disagreements are normal; have a process.

---

See also

• diagnose — the sister skill, for build / sim / test failure triage.
• define-contracts — the contracts the audit checks against.
• references/audit-checklist.md — the full audit rubric.
• references/audit-prompt-template.md — the Codex prompt template.