| name | ie-audit |
| description | Audit a whole codebase, subsystem, or feature against the intent-engineering lenses (predictability, convention, simplicity, experience, and architecture on supported frameworks) and produce a posture report — per-dimension 0-10 scores plus the top surprise/convention/complexity/UX/structural gaps. Use to assess an existing codebase or area, not a specific diff. Sampling-aware for large targets. |
| argument-hint | [mode:agent] [out:<path>] [<path/glob/subsystem to audit, default: whole repo>] |
Intent Engineering — Codebase Audit
Assesses the intent-engineering posture of existing code (no diff). Where
ie-review judges a change, ie-audit judges a body of code: how predictable,
conventional, simple, and usable it is today, scored per dimension with the worst gaps
surfaced first. This is a read-only assessment — it never edits code.
Argument parsing
| Token | Effect |
|---|
mode:agent | Emit JSON instead of markdown. |
out:<path> | Override published report path (file or dir). Defaults: scratch .intense/runs/<run-id>/, publish docs/intent-engineering/<stamp>-audit[-scope].md. |
| remainder | Path, glob, or named subsystem/feature to audit. Default: the repo (excluding deps, build output, generated, and vendored dirs). |
Stage 1 — Scope the target
Resolve the audit set. Be explicit and bounded:
- Determine the file set: the given path/glob, or the repo's source dirs. Exclude
node_modules, vendor, dist/build, generated files, lockfiles, and
artifact dirs (resolved artifacts.run_dir, artifacts.report_dir, legacy
wip/, .intense/runs/, docs/intent-engineering/).
- Detect the stack(s) by extension/manifest to pick
frameworks/<stack>.md docs.
- Sampling rule (large targets). If the set exceeds what lenses can read closely
(rough guide: > ~40 files or very large files), select a representative sample:
the highest-churn / largest / most-depended-on files plus the public entry points
and a cross-section of each layer. State the sampling explicitly — what was and
wasn't covered goes in Coverage. Never silently truncate and imply full coverage.
Stage 2 — Select lenses
First load resolved config per ${CLAUDE_PLUGIN_ROOT}/references/config-resolution.md
(.intense/*.yaml over config/defaults/); the lenses: toggles are authoritative,
and thresholds + pattern policy feed the architecture lens. Note the source in
Coverage. Then read ${CLAUDE_PLUGIN_ROOT}/references/lens-catalog.md.
- Predictability + simplicity always on.
- Convention on when stack/repo standards exist.
- Experience on only if the target has user-facing surfaces.
- Architecture on when a supported framework is detected (Rails:
Gemfile + app/
structure; Python: pyproject.toml/setup.py + .py sources). This is the lens that
audits fat models/routers, God objects/modules, misused services, business logic in
schemas, layer leaks, and classifies/raises patterns — usually the highest-value pass in
a codebase audit. Pass it the resolved thresholds + pattern policy + the
tools.architecture preference (enrich/prefer/report/off).
Honor config lenses: toggles over these defaults. Find repo CLAUDE.md/AGENTS.md
.intense conventions for the convention and architecture lenses. Announce the team.
Stage 3 — Dispatch
Resolve artifact paths per ${CLAUDE_PLUGIN_ROOT}/references/config-resolution.md
(Artifact paths). Shared procedure (skill slug audit):
STAMP=$(date +%Y%m%d-%H%M%S)
RUN_ID="${STAMP}-$(head -c4 /dev/urandom | od -An -tx1 | tr -d ' ')"
OUT_ARG="<out: value or empty>"
RUN_DIR="<artifacts.run_dir or legacy single-bucket or .intense/runs>"
REPORT_DIR="<artifacts.report_dir or legacy or docs/intent-engineering>"
CLEANUP="<artifacts.cleanup_runs; false if legacy single-bucket; default true>"
SKILL_SLUG="audit"
SCOPE_SLUG="<sanitized target slug or empty>"
EXT="md"
RUN="${RUN_DIR}/${RUN_ID}"
mkdir -p "$RUN"
if [ -n "$OUT_ARG" ]; then
case "$OUT_ARG" in
*.md|*.json) REPORT_PATH="$OUT_ARG" ;;
*) REPORT_PATH="${OUT_ARG}/${STAMP}-${SKILL_SLUG}${SCOPE_SLUG:+-}${SCOPE_SLUG}.${EXT}" ;;
esac
else
REPORT_PATH="${REPORT_DIR}/${STAMP}-${SKILL_SLUG}${SCOPE_SLUG:+-}${SCOPE_SLUG}.${EXT}"
fi
mkdir -p "$(dirname "$REPORT_PATH")"
Spawn lenses in parallel with Context: audit (subagent template). Bind
run_artifact_dir = $RUN (Layer A only). Pass model: sonnet to convention,
experience, and architecture; let predictability and simplicity inherit the session model
(their frontmatter default) — don't spawn the always-on lenses as sonnet. Pass the file
set (or sample) and the stack docs to read. Audit mode requires scores — each lens returns 0-10 per
dimension it owns (scoring rubric) plus findings citing file:line. Respect the
concurrency cap. Lenses write $RUN/{lens}.json (via the Write tool).
For very large audits, a lens may itself fan out across file groups; the orchestrator
just needs the merged per-lens return.
Stage 4 — Merge & score
- Validate, dedup, confidence-gate (resolved
confidence_gate, default 75; P0 at 50+
survives) and apply config policy (severity_overrides; suppress approved paths;
keep blocked-pattern findings) as in ie-review Stage 5 (no apply — audit is
read-only).
- Assemble the posture table from each lens's
scores (read
${CLAUDE_PLUGIN_ROOT}/references/scoring-rubric.md): Lens | Dimension | Score | Gap, lowest scores first. Do not average into one number — the gaps are the
product.
- Collect tensions and observations.
Stage 5 — Report
Write the published report to $REPORT_PATH (markdown, or JSON in mode:agent) per
${CLAUDE_PLUGIN_ROOT}/references/report-template.md. Put run_id in the Header. Sections: Header (target,
stack, sampling note, run_id), Posture table (worst first), Findings (P0..P3, grouped, with
Principle + Lens), Tensions, Observations, Coverage (sampling bounds, suppressions,
failed lenses), Verdict = the top 3 posture gaps to fix first with why. No apply,
no push, no time estimates.
Then: if CLEANUP is true, run the guarded cleanup from
${CLAUDE_PLUGIN_ROOT}/references/config-resolution.md (only rm -rf when
$RUN equals $RUN_DIR/$RUN_ID). Always tell the user Report: $REPORT_PATH.
Reference files (read at runtime)
Depends on ${CLAUDE_PLUGIN_ROOT} resolving (standard in Claude Code). Read before
Stage 2 — shared contract for every ie-* skill:
${CLAUDE_PLUGIN_ROOT}/references/config-resolution.md — load/merge .intense config${CLAUDE_PLUGIN_ROOT}/references/lens-catalog.md${CLAUDE_PLUGIN_ROOT}/references/subagent-template.md${CLAUDE_PLUGIN_ROOT}/references/scoring-rubric.md — audit scoring${CLAUDE_PLUGIN_ROOT}/references/findings-schema.json${CLAUDE_PLUGIN_ROOT}/references/report-template.md
