Audit

Arguments: [path] [--diff [<base-ref>]] [--scope <subpath>] [--severity-floor low|medium|high] [--focus all|knowledge|form|D1..D7] [--no-index] [--rebuild-index]. Wherever <arguments> appears below, substitute the text the user typed after the skill name.

/abstraction-architect:audit

Audit a codebase for structural entropy: duplicated domain knowledge, competing sources of truth, redundant representations, duplicated or derivable state, missed unification, prior art that already exists, and abstractions that are fighting their callers. Report-only.

Usage

/abstraction-architect:audit                                    # audit current directory
/abstraction-architect:audit src/services                       # audit a subpath
/abstraction-architect:audit --severity-floor high              # only high-severity findings
/abstraction-architect:audit --focus knowledge                  # D1-D4 only
/abstraction-architect:audit --focus D2                         # competing sources of truth only
/abstraction-architect:audit --diff                             # does my change add entropy?
/abstraction-architect:audit --diff origin/master               # same, against an explicit base ref
/abstraction-architect:audit --rebuild-index                    # ignore any existing concept index

Arguments

• [path] (optional) — codebase root. Default: current working directory.
• --diff [<base-ref>] (optional) — run diff-anchored instead of a whole-codebase audit. Asks the same seven questions as "introduced or aggravated by this change". Base ref defaults to the merge base with the default branch, falling back to HEAD for uncommitted work.
• --scope <subpath> (optional) — limit findings to a subtree. The X-ray still runs on the full codebase.
• --severity-floor low|medium|high (optional) — default medium.
• --focus all|knowledge|form|D1..D7 (optional) — default all. knowledge is D1 to D4, form is D5 to D7, or name a single dimension.
• --no-index (optional) — do not read or write concept-index.json. Use when auditing a directory that is not a git repository, or to measure what the audit finds without a seed.
• --rebuild-index (optional, global mode only) — ignore any existing index and census the codebase from scratch. Use after a large refactor or a history rewrite.

What this command does

1. Resolves the target path. Defaults to the current working directory.

2. Checks for .codebase-xray/. Looks for 01-structure.md, 02-interfaces.md, 03-flows.md, 04-semantics.md. The optional 08-interconnect-map.md enables the bounded-context check; without it, knowledge-track findings carry Bounded-context exception: unverified.

3. Auto-launches X-ray if needed. If .codebase-xray/ is missing or incomplete, prints "No X-ray output found at .codebase-xray/. Launching /codebase-xray:analyze first. This may take several minutes on a large codebase." then invokes it without a confirmation prompt. Aborts with the log path if the X-ray fails.

   Under --diff this step is skipped. Diff mode consumes only 01-structure.md and 02-interfaces.md, uses whatever is on disk, and runs on the concept index plus Glob and Grep when nothing is.

4. Resolves the concept index. Unless --no-index, checks <path>/.abstraction-architect/concept-index.json and runs the freshness script. Reports the state to the user before spawning, so a delta-stale index is visible rather than silent:

   Concept index: delta-stale (baseline a13fe2, HEAD 92ac10, 4 concepts to revalidate)
   

   An absent or unusable index is not an error. The audit proceeds and declares the reduced coverage in its Gaps section.

5. Resolves the diff (--diff only). Runs git diff --name-only <base-ref>...HEAD plus git diff --name-only for uncommitted work, and passes the union as changed_files. Aborts with a clear message when the path is not a git repository.

6. Spawns the abstraction-architect agent via the Agent tool with codebase_path, mode, xray_path, concept_index_path, changed_files under --diff, and the parsed scope, severity-floor and focus flags.

7. The agent writes the report to <path>/.abstraction-architect/findings.md, or findings-diff.md under --diff. In global mode it also rewrites concept-index.json. Diff mode never writes the index.

8. Prints to the user: the report path, summary counts, the concept index state, and the top three findings as one-line previews.

The full report stays in the file so the user opens it deliberately.

Output location

<path>/.abstraction-architect/findings.md, or <path>/.abstraction-architect/findings-diff.md under --diff.

The directory is created automatically if missing. Re-running the command overwrites the previous report.

Prerequisites

• The codebase-xray plugin must be installed (declared as a dependency in marketplace.json). --diff degrades gracefully without X-ray output and reports the reduced confidence in its Gaps section.
• --diff requires the target path to be a git repository.
• For monorepos large enough to benefit from partitioned analysis, run /codebase-xray:team-analyze first to produce 08-interconnect-map.md; the auditor will then include bounded-context fusion findings.

Related commands

• /codebase-xray:analyze — produces the .codebase-xray/ input this command consumes. Auto-launched by this command when missing.
• /codebase-xray:team-analyze — partitioned X-ray for monorepos; adds 08-interconnect-map.md to the output.
• /senior-review:code-review and /senior-review:team-review — both run this agent in diff mode as their abstraction dimension, so a review already answers the "was this already available?" question for the changed code. Use --diff here when you want that check on its own, without the rest of the review.
• /clean-code:clean-code — style and readability cleanup. Different concern.

Out of scope

This command does not produce a refactoring plan. The suggested direction field in each finding names the target layer or refactoring move in one sentence.