| name | audit-project |
| description | Orchestrates the four ataraxis audits in the order and concurrency their dependencies require, and merges their findings into one deduplicated report. Runs in full mode over a repository, package, or directory, or in change mode over the files a feature, bugfix, or refactor touched, where it gates the work until the new code passes. Use when completing any implementation task, before committing, when auditing a project end to end, or when the user invokes /audit-project. |
| user-invocable | true |
Project audit orchestration
Runs /audit-facts, /audit-correctness, /audit-performance, and /audit-style as one pass, resolves the ownership
collisions between them, and produces a single merged report.
You MUST read this entire skill, and load each reference file at the step that names it, before acting on that step. The
verification checklist at the end is mandatory before presenting the report.
Scope
Covers:
- Selecting which of the four audits a target actually needs, and sequencing them
- Asking the user whether wave 2 runs, rather than sweeping a whole project for bugs and cost unasked
- Running the shared discovery ONCE, so four audits stop re-deriving one inventory, one set of prerequisites, one
coverage ranking, and one callgraph
- Full mode over a repository, a package, or a directory
- Change mode over the files a feature, bugfix, or refactor touched, together with the fix-and-recheck loop that gates
the work until the new code passes
- Telling
/audit-style whether its project-scope layout pass applies, which it does once per run for a project root
and never for a package or a single-file target
- Merging, deduplicating, and adjudicating findings across the four audits into one report
Does not cover:
- The detection work itself, which each audit owns and this skill never duplicates
- Code, documentation, or configuration modifications. The audits produce findings only, and the change-mode fixes
happen OUTSIDE them, between rounds
- Committing, pushing, or opening a pull request (see
/commit and /pr)
- Codebase exploration (see
/explore-codebase)
The two modes
| Mode | Target | Trigger |
|---|
| Full | A repository, package, or directory | The user asks for a project audit |
| Change | The files a unit of work touched | Implementation work finished, or the user names a diff |
Change mode is the ONE sanctioned use of the explicit change-set scoping each audit defines. Every audit keeps
whole-target coverage as its own default, and only this skill's change mode narrows it.
Full mode never resolves a diff. A user who asks to audit the repository gets the repository.
Sequence and concurrency
Four audits share one file set, so the question is which of them may read the same files at the same time and which must
wait for another's verdict.
Real dependencies. Only these three exist, and everything else is independent.
| Consumer | Depends on | What flows |
|---|
| Every audit | Shared context | File inventory, prerequisites, coverage ranking, callgraph |
/audit-correctness | /audit-facts | The DRIFT and WRONG verdicts its ownership ladder routes on |
/audit-performance | Shared context | The callgraph its hot-path census turns into multiplicity |
The order each audit states in its own Proactive behavior, which is facts, then correctness, then performance, then
style, is a FIX order. It exists because applying a fix from an earlier audit changes what a later audit would judge. No
audit modifies anything, so that order constrains the sequence in which the USER acts on the report rather than the
sequence in which the audits run.
Waves. Run the audits in two waves, and run the members of a wave concurrently.
| Wave | Audits | Why they may share a wave |
|---|
| 1 | /audit-facts, /audit-style | Neither reads the other's output |
| 2 | /audit-correctness, /audit-performance | Both read the shared context, not each other's output |
Facts owns the claim inside a documentation block and style owns the form of that block, so wave 1 splits cleanly. What
sits between the wave 2 members is a routing rule rather than a data dependency, so the merge step settles it after both
finish.
Wave 1 completes before wave 2 starts, because /audit-correctness adjudicates the ownership ladder against wave 1's
documentation verdicts. Wave 1 also runs the deterministic gates, whose diagnostics every later wave reads instead of
re-deriving.
The project-scope layout pass. Wave 1 also carries /audit-style's sweep of the project directory tree against its
archetype. That sweep runs once per run, on the main agent and never inside a batch sub-agent, and ONLY where the
resolved target is a project root, because a package or a single file carries no tree to judge. In change mode it
additionally requires that the change set CREATES or DELETES a file. Tell /audit-style which case applies, so the pass
runs once rather than once per batch or not at all, and carry the status it reports, in the vocabulary Step 0 states,
into the merged coverage ledger.
Parallelize at exactly ONE level. Each audit already fans out internally over file batches, and nesting a fan-out
inside a fan-out multiplies the instruction payload by both factors. A target under 10 files parallelizes at the WAVE
level, and a target of 10 or more files parallelizes at the BATCH level.
The level table, the shared-context schema, and the sub-agent budget live in
execution-plan.md.
Workflow
You MUST follow these steps when this skill is invoked.
Copy this progress checklist into your response and check off items as you complete them:
Project Audit Progress:
- [ ] Step 0: Mode resolved, target resolved, wave 2 elected, plan confirmed
- [ ] Step 1: Shared context built
- [ ] Step 2: Audits selected and the ones not running recorded
- [ ] Step 3: Wave 1 complete (facts, style)
- [ ] Step 4: Wave 2 complete, or skipped because the election kept neither
- [ ] Step 5: Findings merged and ownership collisions adjudicated
- [ ] Step 6: Report produced, and in change mode the gate applied
Step 0: Resolve the mode and the target, then pause
Resolve the mode from the invocation. Implementation work that just finished resolves to change mode. A named
repository, package, or directory resolves to full mode. Ask when neither is clear.
Emit ONE plan covering the whole run:
- The mode, and for change mode the base revision and the resolved file list
- Files in scope, grouped by language and by kind, with counts
- Which of the four audits will run, and which are not running with the reason
- The wave 2 election below, stated as a question the user answers
- The parallel level the target size selects
- Whether the
/audit-style project-scope layout pass runs, stated as run, skipped-not-a-project-root, or
skipped-no-created-or-deleted-files
- Whether coverage artifacts are present, stale, or absent
Pause for user confirmation or a "proceed" signal.
This plan REPLACES the Step 0 plan of each individual audit. Tell every audit that its own Step 0 is already satisfied
and that it MUST NOT pause again, otherwise four separate confirmations interrupt one run.
The wave 2 election
Wave 1 is not elective. /audit-facts and /audit-style run wherever they have files, because documentation drift and
convention drift accumulate across a whole target and are read that way.
Wave 2 IS elective, and you MUST ask for it explicitly rather than inferring it from the target. Put the question in the
plan with all four answers stated:
| Answer | Wave 2 runs |
|---|
| Both | /audit-correctness and /audit-performance |
| Correctness only | /audit-correctness |
| Performance only | /audit-performance |
| Neither | Wave 1 alone, and the run ends after it |
Recommend NEITHER in full mode. A correctness or performance sweep over a whole project returns a report scoped to
nothing the user chose, and both are acted on one module at a time rather than one repository at a time. A user who
wants them names the module, and that naming is the scoping those two audits were built around.
Recommend what the routing table selects in change mode, because a change set is already that scoping.
Ask nothing where the target holds neither a source nor a test file. Step 2's bound-file-set rule already drops
both wave 2 members there, so the election has nothing to decide. A target holding tests alone still keeps
/audit-correctness bound for its Pass 10, so the election runs.
Step 1: Build the shared context
Build it ONCE on the main agent, and write it to the session scratch directory. Every audit RECORDS it rather than
re-deriving it, and it stands as the output of the discovery steps that audit would otherwise run. Those steps are Step
1 for /audit-facts and /audit-style, Steps 1 through 3 for /audit-correctness, and Steps 1 and 2 for
/audit-performance.
The schema is in execution-plan.md. It carries the file inventory with each file's
authority binding, the per-language prerequisites, the coverage ranking, and the CONTRACT, STATE, and CALLGRAPH ledgers.
Building this once is what stops a four-audit run from reading the same file set four times.
Step 2: Select the audits
Both modes select from what the target actually CONTAINS rather than from file extensions alone, and wave 2 additionally
requires the Step 0 election. An audit that did not run is recorded in the report with its reason, so a thin run is
visible rather than silent.
Change mode routes with the routing table in change-mode.md, which reads the change set and
recommends the wave 2 election.
Full mode never narrows an audit, and it runs every audit that has something to read. Membership comes from the kind
field of the Step 1 inventory rather than from a change set:
| Audit | Bound file set | Skipped when |
|---|
/audit-facts | Metadata and in-source documentation | Neither class is present |
/audit-style | Every file matching its binding table | No file matches a binding row |
/audit-correctness | source, plus test for Pass 10 | Neither kind is present |
/audit-performance | source | No source file is present |
A documentation-only, skill-only, or configuration-only target therefore runs wave 1 alone. Spawning an audit whose
bound file set is empty pays its whole instruction payload for a report that cannot hold a finding, and it spends
sub-agent budget the audits with work still need.
Two reductions apply, and they compose. The bound-file-set rule above drops an audit with nothing to read, and the Step
0 election drops a wave 2 audit the user declined. Record each under its own reason, because a DECLINED audit was
offered and an EMPTY one could never have run.
Neither reduction narrows an audit that does run. It covers the whole target, and no finding is dropped because the
target is small or unusual.
Step 3: Run wave 1
Run /audit-facts and /audit-style at the parallel level Step 0 selected. Hand each one the shared context, the
change-set narrowing where change mode applies, and the instruction that its Step 0 is satisfied.
Collect the deterministic-gate diagnostics /audit-style produced into the shared context, so wave 2 reads them rather
than re-deriving them.
Step 4: Run wave 2
Run the members the Step 0 election kept, at the same parallel level. Hand /audit-correctness wave 1's DRIFT and WRONG
verdicts alongside the shared context, so its ownership ladder adjudicates against findings that already exist rather
than re-deriving them.
Where the election kept neither, skip wave 2 and go to Step 5, which merges wave 1 alone. Where it kept one, that audit
runs by itself and the wave costs one sub-agent rather than two.
Step 5: Merge and adjudicate
Apply the rules in report-merge.md, which deduplicate one construct reported by two
audits, resolve the four ownership collisions the audits leave to a caller, and collapse one root cause reported at
several sites.
Every finding keeps the severity, impact, confidence, and evidence its owning audit assigned. This step removes
duplicates and settles ownership, and it never re-rates a finding.
Step 6: Produce the report and apply the gate
Use the output format below.
In full mode the report is the deliverable, and the run ends there.
In change mode, apply the gate in change-mode.md. A BLOCKED verdict names the findings that
must be resolved, hands them back for fixing OUTSIDE the audits, and re-runs the audits over the union of the original
change set and the files the fixes touched. Three rounds cap the loop, after which the report states what remains and
the decision passes to the user.
Output format
Open with the merged triage header from report-merge.md, then the combined coverage
ledger, then the findings. Both layouts are given there verbatim, and this skill emits them unchanged.
Group the findings by AUDIT, then follow each audit's own ordering inside its section, including its trailing LOW
confidence appendix. A reader who wants one audit's report finds it whole rather than interleaved with three others.
Every finding keeps the shared shape its own audit defines, which is a stable ID, a rank, a location line, and the
Wrong, Fix, and Impact bullets, with a Choice bullet where the audit cannot settle the question. The four audits use
distinct ID letters, C for correctness, P for performance, S for style, and F for facts. Identifiers therefore
stay unique across the merged report, and a reader answers with one identifier rather than with a file and a line.
A finding that survived adjudication against another audit names the audit that yielded and the rule that decided it at
the end of its Wrong bullet.
Discipline
You MUST adhere to the following discipline during every run.
- Never perform detection work yourself. This skill selects, sequences, and merges, and every finding comes from an
audit that produced it under its own evidence floor.
- Never apply a fix inside an audit. Fixes happen between rounds, outside the audits, and the next round re-audits the
files they touched.
- Never resolve a finding by weakening a test, a contract, a docstring, or a coverage setting. A gate satisfied that way
is a gate defeated.
- Never apply a fix that breaks the public API or alters public behavior without the user's explicit approval, whatever
the severity and whatever the gate. Present it, name what breaks and who calls it, and WAIT. See the approval section
in change-mode.md.
- Record every audit that did not run under its own reason, DECLINED or EMPTY or a routing row, and every capped loop
with what remained.
- Fill each line the plan, the gate verdict, and the merged header write to 120 characters before breaking it, under
the wrap width rule
/python-style defines. A line ending before column 100 while its next word would still fit is
re-flowed.
Related skills
| Skill | Relationship |
|---|
/audit-facts | Wave 1 member, owns documentation claims that disagree with the code |
/audit-style | Wave 1 member, owns style, formatting, and documentation quality |
/audit-correctness | Wave 2 member, owns active and latent bugs and broken stated contracts |
/audit-performance | Wave 2 member, owns cost, speed, memory use, and dtype predictability |
/explore-codebase | Provides project structure context, invoke first on an unfamiliar codebase |
/explore-dependencies | Provides ataraxis API snapshots the audits verify library calls against |
/commit | Runs after a change-mode gate passes, and never before it |
/pr | Drafts the pull request summary after a change-mode gate passes |
Proactive behavior
Invoke this skill in change mode after completing any unit of implementation work, which covers a feature, a bugfix, a
refactor, and a documentation change, and BEFORE offering to commit. The point is that new code passes the audits it is
subject to while the work is still in context.
Invoke it in full mode when the user asks to audit a project, a package, or a repository, rather than running the four
audits by hand in sequence.
Prefer this skill over invoking a single audit whenever more than one audit applies to the target, because a
single-audit run pays the shared discovery again and produces a report a reader must merge by hand.
Invoke /audit-correctness or /audit-performance DIRECTLY when the user names a module and wants one of them over it.
That narrow, deliberate run is what those two audits are built for, and routing it through this skill adds an
orchestration a single-audit target does not need.
Do NOT make code changes during an audit round. Present findings and, in change mode, fix between rounds rather than
inside them.
Verification checklist
You MUST verify the run against this checklist before presenting the report.
Project Audit Orchestration Compliance:
- [ ] Mode resolved explicitly, and change mode used only for a change set
- [ ] One plan produced and confirmed before any audit started
- [ ] Every audit told its Step 0 is satisfied, and none paused again
- [ ] Shared context built once on the main agent and handed to every audit
- [ ] No audit re-derived the inventory, prerequisites, coverage ranking, or callgraph
- [ ] Audits selected by what the target contains, with every audit that did not run recorded
- [ ] Wave 2 election asked explicitly at Step 0, with all four answers offered
- [ ] Neither wave 2 audit run without the user electing it, and any decline recorded as DECLINED
- [ ] Wave 1 completed before wave 2 started
- [ ] Members of each wave run concurrently at the parallel level the target size selected
- [ ] Parallelism applied at exactly one level, never wave and batch together
- [ ] Deterministic-gate diagnostics collected in wave 1 and reused by wave 2
- [ ] Project-scope layout pass status collected from /audit-style and carried into the merged ledger
- [ ] /audit-correctness received wave 1's DRIFT and WRONG verdicts for its ownership ladder
- [ ] Findings merged, with one construct reported by two audits resolved to one owner
- [ ] Every adjudicated finding carries the audit that yielded and the rule that decided it
- [ ] No finding re-rated, and every severity, impact, confidence, and evidence left as its audit assigned
- [ ] Merged triage header present, carrying per-audit counts and every discard count
- [ ] Each audit's section preserves its own output format, ordering, and LOW confidence appendix
- [ ] In change mode, the gate verdict stated and every blocking finding named
- [ ] In change mode, fixes applied between rounds rather than inside an audit
- [ ] Every public API break and public behavior change presented for approval and waited on
- [ ] No fix needing approval applied to reach a PASSED verdict
- [ ] In change mode, each re-run covered the original change set plus the files the fixes touched
- [ ] Loop capped at 3 rounds, with anything remaining stated in the report
- [ ] No finding resolved by weakening a test, a contract, a docstring, or a coverage setting
- [ ] Plan, gate verdict, and merged header prose fill each line to 120 characters, with no line ending before column
100 while its next word would still fit
- [ ] No file modifications made during any audit round
