audit-style

name	audit-style
description	Performs a thorough style-compliance audit of source code, configuration, or documentation files against the applicable ataraxis framework style skill checklists. Walks every line in scope and reports only non-compliant findings with verbatim checklist citations. Use when auditing a Python package, config file, README, or any project file for style, formatting, naming, or convention compliance, or when the user invokes /audit-style.
user-invocable	true

Style compliance audit

Audits files against the authoritative ataraxis framework style skill checklists, reporting only non-compliant findings with verbatim checklist citations.

You MUST read this entire skill, and load each reference file and each style skill checklist at the step that names it, before acting on that step. The verification checklist at the end is mandatory before submitting findings.

---

Scope

Covers:

• Auditing single files, directories, or full project trees against applicable style skills
• Running the project's own linters, formatters, and type checkers in their read-only form, and folding their diagnostics into the report as findings
• Structural style: element ordering, imports, formatting, naming, type annotations, error-handling patterns, file-section ordering
• Symbol visibility and usage: each symbol's declared tier against the widest boundary its consumers actually cross, the package export lists against the set of packages importing from them, and assets that no consumer references
• Project-scope layout: the repository directory tree against the archetype tree its indicators resolve to, for a project-root target
• Comment and docstring quality: typos, sentence length, length proportionality, redundancy with the type signature, narrate-the-code comments, separator punctuation, and behavioral scope
• Cross-file consistency: naming, ordering, and idiom drift across the file set
• Cross-skill conflicts where two loaded style skills disagree on the same point

Does not cover:

• Factual accuracy of documentation against source code, including stale references and docstring claims that disagree with the implementation (see /audit-facts)
• Active and latent bugs, and behavior that breaks the contract the code states (see /audit-correctness)
• Cost, speed, memory use, and dtype predictability, which covers the runtime consequence of a construct whose form this skill judges (see /audit-performance)
• Code modifications or style fixes (this skill produces findings only), which includes every auto-fixing and reformatting tool invocation
• Re-deriving by reading any rule the project's own tools already decide
• Inventing new conventions not present in any loaded style skill checklist
• Codebase exploration (see /explore-codebase)

---

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:

Audit Progress:
- [ ] Step 0: Plan produced and confirmed
- [ ] Step 1: Target resolved, style skills bound, tier selected
- [ ] Step 2: Style skill checklists loaded and rule ledger built
- [ ] Step 3: Deterministic gates run and their findings collected
- [ ] Step 4: Project-scope layout sweep run, or skipped and recorded
- [ ] Step 5: Line-by-line sweep complete (all four dimensions)
- [ ] Step 6: Severity and confidence assigned
- [ ] Step 7: False-positive guards applied
- [ ] Step 8: Findings verified (citation, refutation)
- [ ] Step 9: Coverage ledger assembled
- [ ] Step 10: Report produced

Step 0: Produce audit plan and pause

Emit a plan before any sweep work fires. The plan must list:

• Files in scope (resolved absolute paths)
• Style skills bound to those files, meaning the authority each one resolves to in the Step 1 table
• Tier classification (small, medium, or large)
• Whether the Step 4 project-scope layout sweep runs, and the reason when it does not
• Whether the Pass 11 symbol usage sweep runs in full, runs partially, or is skipped, with the reason
• Expected finding severities

Pause for user confirmation or a "proceed" signal. This catches misidentified targets before tokens burn on the wrong scope.

Step 1: Resolve target and bind style skills

Resolve the target (a single file, a package directory, or a project root) into the set of files in scope. For directory or project-root targets, every file under the target is in scope. There is no "covered area" reduction.

Whole-repository coverage is the default and stays the default. Narrow to a change set ONLY when the user asks for that in the invocation, resolving it with git diff --name-only <base>...HEAD for a branch, git diff --name-only <commit> for one commit, or git status --porcelain for the working tree. A narrowed run still reads every surviving file in full, because ordering, visibility grouping, and length proportionality are properties of a whole file. It also still builds the Step 5 reference table across the WHOLE repository, because a symbol's tier is decided by consumers a change set does not contain. Guard 16 skips the usage pass outright rather than deciding an absence from a partial table. Record the narrowing and the revision it resolved against in the report, so it states what it did not cover.

For each file in scope, identify the applicable style skill using the binding table:

File pattern	Authority
*.py, *.pyi	/python-style
*.cs, .editorconfig, .csharpierrc.yaml, .csharpierignore	/csharp-style
*.h, *.hpp, *.cpp, .clang-format, .clang-tidy, CMakeLists.txt	/cpp-style
README.md	/readme-style
pyproject.toml	/pyproject-style
tox.ini	/tox-config
platformio.ini, library.json	/platformio-config
docs/**/*.rst, docs/**/conf.py, Makefile, make.bat, Doxyfile	/api-docs
SKILL.md, skill references/*.md, CLAUDE.md, AGENTS.md	/skill-design
.github/ISSUE_TEMPLATE/*.yml	/project-layout
envs/*	/project-layout
Project directory tree	/project-layout

Where a file matches more than one row, the MOST SPECIFIC pattern wins, which resolves docs/source/conf.py to /api-docs rather than to any broader row it also matches. The Project directory tree row binds no file at all and is executed by the Step 4 layout sweep rather than by the per-file passes.

A .pyi stub file binds to /python-style for its generated-stub rule alone. Judge it against that rule rather than against the ordinary source checklist, so the one finding it can carry is evidence of hand-authoring in a file the stub generator writes.

If a file in scope matches no binding row, no style skill applies to it. Mark it skipped in the plan and report, with the reason no binding row, and flag no findings against it.

Classify the audit tier, and note that the three rows partition the file count with no overlap and no gap:

Tier	Indicators	Execution
Small	1 file	Main agent, sequential
Medium	2 to 9 files	Main agent, file-by-file
Large	10 or more files or a project root	Parallel general-purpose sub-agents over file batches

Batching isolates the style guides. A Large-tier audit BATCHES BY AUTHORITY, so no sub-agent carries more than one or two checklists. Each one loads ONLY the checklists its own batch binds to, together with ONLY the rule-ledger rows Step 2 built from them. Only the per-file sweep fans out, and every batch returns the Pass 11 declaration and reference rows alongside its findings. See the "Batching the fan-out" section of detection-passes.md for the three batch-construction rules, the sub-agent caps, the main-agent split, and the agent-type prohibition.

Step 2: Load applicable style skill checklists

Run Pass 1 from detection-passes.md, which builds the rule ledger every later pass reports against.

For every distinct style skill the bindings resolve to, invoke that skill and load its full verification checklist along with every reference file the skill mentions. The loaded checklists are the only source of truth for "applicable style point." A convention not present in any loaded checklist is NOT a violation.

Tag every ledger row with the batch that will consume it, so Step 5 hands each sub-agent its own rows rather than the whole ledger.

Step 3: Run the deterministic gates

The project's own tools already decide every rule that can be decided mechanically, and they decide it correctly every time. Run them FIRST, read their output as findings, and spend the sweep on the rules no tool can check.

Run only the READ-ONLY forms. Bare tox and tox -e lint are FORBIDDEN during an audit, because the lint environment reformats the source, auto-fixes it, and purges its stubs, which mutates the very code under audit.

Tool	Read-only invocation
ruff lint rules, for Python files	ruff check --no-fix --output-format=json .
ruff formatting, for Python files	ruff format --diff .
mypy, where the project configures it	mypy .
clang-format, for C++ files	clang-format --dry-run --Werror <files>
clang-tidy, where a .clang-tidy file exists	clang-tidy <files>

A tool the project does not configure is skipped, and its absence is no finding. Report a tool that failed to run as a gap in the coverage the report states rather than as a clean result.

Fold each diagnostic into the report as an ordinary finding, citing the tool and its rule code in place of the checklist quote, at HIGH confidence. A diagnostic a tool produced needs no adversarial verification in Step 8, because the tool IS the external check.

Then narrow the Step 5 sweep. The passes still run, and their scope shrinks to what the tools cannot decide. Guard 2 of false-positive-guards.md lists the rules the tools own, and the "What the sweep keeps" section of detection-passes.md lists the rules the sweep retains.

State in the report which tools ran and which rules the sweep therefore delegated.

Step 4: Sweep the project layout

Run Pass 10 from detection-passes.md, which defines the four-part procedure and the finding shape this sweep reports in. The directory tree is a style surface no per-file pass can reach, because a pass reading a file cannot report the file that is MISSING. The sweep runs ONCE, on the main agent, before the per-file batches fan out, never inside a batch sub-agent.

Run it ONLY when the resolved target is a project root, and in change mode only when the change set CREATES or DELETES files. Otherwise the sweep is SKIPPED, and the Step 0 plan and the Step 9 coverage ledger each record it as skipped-not-a-project-root or skipped-no-created-or-deleted-files. Silence is never coverage, so an unrecorded skip reads as a clean tree that nothing ever checked. Every layout finding passes through the Step 7 guards like every other candidate.

Step 5: Line-by-line sweep

Run passes 2 through 8 from detection-passes.md in order, over ONE traversal of each file rather than one traversal per pass. Passes 9 and 11 run after that traversal closes, on the main agent. Passes 2 through 6 cover Dimension A, passes 7 and 8 cover Dimension B, pass 9 covers Dimension C, and pass 11 covers Dimension D.

For every file in scope, walk top to bottom. For every line, evaluate against every applicable checklist item. Track four parallel dimensions.

Dimension A, structural style: Element ordering, imports, formatting, naming, type annotations, error-handling patterns, and file-section ordering. The source of truth is the loaded style skill's main checklist.

Dimension B, comment and docstring quality: Apply the loaded style skill's docstring and comment checklist to every comment, docstring, and inline annotation, judging the FORM of the prose rather than its factual accuracy. Passes 7 and 8 of detection-passes.md carry the eleven checks, which cover typos, grammar, sentence length, length proportionality, redundancy with the signature, narrate-the-code comments, behavioral scope, separator punctuation, and positive description.

Dimension C, cross-file consistency: Naming, ordering, and idiom drift across the file set. Examples include the same field named differently in two sibling classes, or one module following a convention that adjacent modules ignore.

Dimension D, symbol visibility and usage: Each symbol's declared tier against the widest boundary its consumers actually cross, and each symbol's consumer set against emptiness. Pass 11 of detection-passes.md names the five findings this dimension can produce. Every one is a claim about ABSENCE, so each is confirmed by a repository-wide search before it is reported, and Guard 15 discards the candidates resting on a consumer no written reference reveals.

While traversing each file, record the symbols it DECLARES and the symbols it REFERENCES, so Pass 11 can reconcile the two tables on the main agent once the traversal closes.

List ALL violations in each pass. Do NOT stop at the first.

For Large-tier audits, spawn one general-purpose sub-agent per batch under the Step 1 rules. Each sub-agent receives its batch's file paths, ONLY the checklists those files bind to, ONLY the rule-ledger rows built from those checklists, the Step 3 diagnostics for those files, and the severity and confidence rules. Sub-agents return findings in the output format defined below, together with the Pass 11 declaration and reference rows for their own files. The main agent synthesizes after all sub-agents complete, then runs passes 9 and 11 over the merged result.

For Small and Medium tiers, the main agent performs all sweep work sequentially.

Step 6: Assign severity and confidence

Assign every violation one of these severities:

Severity	Meaning
BLOCKING	Checklist explicitly states "MUST" or "blocks release"
STANDARD	Checklist convention without an explicit blocking flag
INCONSISTENCY	File or file set mixes schemes the checklist permits only separately
CONFLICT	Two loaded style skills disagree on the same point

Also assign a confidence tier to every finding:

Confidence	Meaning
HIGH	Verbatim checklist quote and verbatim source quote both present
MEDIUM	One quote verbatim, the other requires interpretation
LOW	Pattern detected but checklist/source mapping is inferred, not literal

Step 7: Apply the false-positive guards

Walk every candidate through every guard in false-positive-guards.md, in order. The rule-ledger guard runs first and removes the most candidates. Discard everything a guard rejects, and record the count of discarded candidates for the report's triage header.

Step 8: Verify the surviving findings

Run the two checks in verification-protocol.md, in order:

1. Citation verification, against every surviving finding with no sampling. Confirms the quoted checklist point appears in the loaded checklist and the quoted current state appears at the cited line.
2. Adversarial refutation, against every BLOCKING and CONFLICT finding. A fresh general-purpose sub-agent per finding, instructed to refute it and to answer REFUTED under uncertainty.

Both checks are external, testing the finding against the files and against a reader who never saw the sweep. They catch the failure mode this audit produces most often, which is misapplying a checklist rule. A Step 3 diagnostic skips both checks, because the tool that produced it already is the external check. Record every count the protocol names, because the report's triage header carries them.

Step 9: Assemble the coverage ledger

Build the coverage ledger the report carries under its triage header, in the shape verification-protocol.md defines. It exists so a thin pass is visible rather than silent.

Skipping is permitted only for a file the user's narrowing removed from scope, a file matching no binding row, a generated or vendored file Guard 5 removes, or a file that cannot be read. A file in scope that is neither audited nor recorded as skipped is a coverage gap rather than a permitted skip.

Step 10: Produce the findings report

Use the output format below.

Skip compliant items entirely. Report every surviving finding at every confidence tier by default, which covers LOW alongside HIGH and MEDIUM. Narrow the report to HIGH and MEDIUM only when the user explicitly asks for it via --min-confidence medium or equivalent invocation.

The confidence tier stays on every finding, so a reader triages by tier rather than by trusting that the report was filtered. LOW means the checklist and source mapping is inferred rather than literal, and it never excuses a finding from the verbatim checklist quote the Discipline section requires. Hold the report's own prose to the rules this audit enforces, keeping every sentence in an authored field under 40 words and separating its clauses with full stops and commas rather than semicolons or em-dashes. Fill each authored line to 120 characters before breaking, under the wrap width rule /python-style defines, so a line ending before column 100 while its next word fits is re-flowed.

---

Output format

Open the report with the triage header from verification-protocol.md, then the Step 9 coverage ledger. The header carries the finding counts by severity and confidence, the tools Step 3 ran, and every discard count. The same protocol defines the grouping, which is file, then severity, with the severities ordered BLOCKING, INCONSISTENCY, CONFLICT, STANDARD, and the trailing Appendix: LOW confidence section.

Step 4 layout findings belong to no file, so they sit in a leading Project layout group ahead of the per-file groups, headed by the archetype the sweep resolved and the indicators that resolved it.

Every finding uses the shape below, shared by all four audits in this family so one reading habit serves them all.

### <ID> · <BLOCKING | STANDARD | INCONSISTENCY | CONFLICT> · <one-line statement of the defect>

`<path>:<line>` · <owning skill or tool> · <HIGH | MEDIUM | LOW> confidence · <checklist point or rule code>

- **Wrong:** <the defect, carrying every quote and citation the evidence floor requires>
- **Fix:** <the concrete change, described rather than applied>
- **Impact:** <what the change alters for callers and downstream, or "None" when nothing observable changes>
- **Choice:** <the options, one clause each, closing with a recommendation>

ID is a short stable handle, S1, S2, and so on, numbered in report order, so a reader answers with the identifier rather than by restating the finding.

Wrong carries the whole evidence load as prose rather than as labelled fields. It states the checklist point quoted verbatim from the skill or reference file that states it, the current state quoted verbatim at its <path>:<line>, and the required state as a concrete example or the checklist's own wording. A table, a ledger, or an interleaving sits directly beneath the bullet.

Impact states what the fix alters for a caller or a downstream project, and states "None" when the change is behavior-preserving. Naming a break here IS the signal that the fix needs the owner's decision.

Choice appears only where the audit cannot settle the question, covering a CONFLICT between two skills, which only the owner resolves. Each option gets one clause, and the bullet closes with a recommendation.

Impact covers REMOVAL alongside renaming and re-signaturing. Deleting a symbol, dropping an __all__ entry, and demoting a public name to an underscore each break a caller exactly as a rename does, so each names that break.

When the same checklist point is violated several times within one file, collapse it to a single finding whose location line carries the site list and a count, written as `module.py:47, 89, 112, 134` · 4 occurrences.

A Step 4 layout finding cites no line, because <path>:<line> cannot point at a file that does not exist. Its location line carries the archetype slot instead, as Pass 10 in detection-passes.md defines. A Pass 11 symbol usage finding adds the consumer evidence and the search that established it to its Wrong bullet.

---

Discipline

You MUST adhere to the following discipline during every audit.

• Anchor every finding to a verbatim checklist quote. No checklist quote, no finding.
• Never invent an exemption. An exemption exists only where a loaded skill writes it down, and you MUST quote that clause before applying it. Shared corpus, house convention, text byte-identical in a sibling repository, long-standing code, and "it reads fine" are none of them, so a real finding survives wherever else the same text appears.
• Never flag subjective preferences (tone, ordering, terminology) unless the loaded checklist explicitly requires the convention.
• If a file carries an auto-generated block, or an exemption a loaded skill writes down, note the exemption with its verbatim clause and skip its enclosing range.

---

Related skills

Skill	Relationship
/audit-project	Orchestrator that runs this audit in wave 1 and merges it with the siblings
/audit-facts	Sibling audit for factual accuracy of documentation against source code
/audit-correctness	Sibling audit for active and latent bugs and broken stated contracts
/audit-performance	Sibling audit for cost, speed, memory use, and dtype predictability
/python-style	Provides the Python checklist, loaded when scope contains Python files
/cpp-style	Provides the C++ checklist, loaded when scope contains C++ files
/csharp-style	Provides the C# checklist, loaded when scope contains C# files
/readme-style	Provides the README checklist, loaded when scope contains README files
/pyproject-style	Provides the pyproject.toml checklist, loaded when that file is in scope
/tox-config	Provides the tox.ini checklist, loaded when that file is in scope
/platformio-config	Provides the platformio.ini and library.json checklist, loaded for those files
/api-docs	Provides the Sphinx docs checklist, loaded when scope contains docs files
/skill-design	Provides the skill, CLAUDE.md, and AGENTS.md checklist, for those files
/project-layout	Provides the directory and issue template checklist, for roots and .github
/explore-codebase	Provides project structure context, invoke first on an unfamiliar codebase
/explore-dependencies	Provides ataraxis API snapshots the Python checklist's library preferences need

---

Proactive behavior

Invoke this skill when the user asks to audit a file, package, or project for style compliance.

Apply its findings LAST, after the fixes from /audit-facts, /audit-correctness, and /audit-performance, when auditing the same file end to end. Style fixes applied before factual corrections waste effort on prose that may be rewritten, and correctness and optimization fixes change the code whose form this skill judges. That is a FIX order, and /audit-project decides the RUN order.

Do NOT make code or documentation changes during the audit. Present findings and wait for user direction.

---

Verification checklist

You MUST verify the audit output against this checklist before presenting it to the user.

Style Audit Compliance:
- [ ] Step 0 plan produced and confirmed by user before sweep began
- [ ] Plan stated whether the symbol usage sweep runs in full, runs partially, or is skipped
- [ ] Tier classified (small/medium/large) and agent allocation matched the table
- [ ] For Large tier, batches built by authority with no batch carrying more than two checklists
- [ ] For Large tier, every single-file authority, each skill batch, and the docs package given its own sub-agent
- [ ] For Large tier, each sub-agent loaded only its own batch's checklists and rule-ledger rows
- [ ] Sub-agents held to 40 for the run and 12 in flight, merging to fit rather than dropping files
- [ ] Scope narrowed to a change set only on explicit request, with the revision recorded in the report
- [ ] Step 1 file binding executed (every file in scope mapped to its applicable style skill)
- [ ] `.pyi` stubs judged against the generated-stub rule alone, with no ordinary source findings reported inside them
- [ ] Step 2 checklists loaded for every applicable style skill
- [ ] Step 3 deterministic gates run in their read-only form for every tool the project configures
- [ ] Bare `tox` and `tox -e lint` never run during the audit
- [ ] Tool diagnostics folded in as findings citing the tool and rule code, at HIGH confidence
- [ ] Rules the tools decide delegated to them rather than re-derived by the sweep
- [ ] Report states which tools ran, which failed to run, and which rules were delegated
- [ ] Step 4 layout sweep run once on the main agent for a project-root target, before the batches fanned out
- [ ] Layout sweep skipped and recorded for a package, single-file, or edit-only change-set target
- [ ] Archetype resolved from the /project-layout key indicators, with the deciding indicators recorded
- [ ] Archetype tree loaded from project-layout/references/archetype-trees.md and diffed against the real tree
- [ ] Layout checklist presence and absence items applied (envs/, .github/ISSUE_TEMPLATE/, .netlify-site)
- [ ] Every file in scope walked top to bottom
- [ ] Rule ledger built in Pass 1, with every rule copied verbatim from a loaded checklist
- [ ] Detection passes 2 through 8 run in order over one traversal of each file
- [ ] Pass 9 run on the main agent over the whole file set, after that traversal closed
- [ ] Pass 10 run on the main agent for a project-root target, or skipped with the reason recorded
- [ ] Pass 11 run on the main agent over the whole file set, or skipped with the reason recorded
- [ ] Declaration and reference rows collected during the single traversal, and returned by every batch sub-agent
- [ ] Reference table built across the whole repository even where the sweep was narrowed to a change set
- [ ] Every symbol's declared tier compared against the widest boundary its consumers actually cross
- [ ] Each package export list compared against the set of packages importing from it, in both directions
- [ ] Every Pass 11 candidate confirmed by a repository-wide search, with the search result quoted
- [ ] Every Pass 11 finding carries its consumer evidence and the search that established it
- [ ] Citation verification re-ran each Pass 11 search rather than accepting the recorded result
- [ ] Guard 15 applied, so curated public API, runtime registrations, interface conformance, and generated
      declarations produced no usage finding, and test references counted as no consumer
- [ ] Unused imports, locals, and arguments left to ruff rather than re-derived by the usage pass
- [ ] All four dimensions evaluated (structural, comment/docstring quality, cross-file consistency,
      symbol visibility and usage)
- [ ] Every finding anchored to a verbatim checklist quote, or to a tool rule code
- [ ] Every finding cites <path>:<line>, or the expected or offending path for a layout finding
- [ ] Every finding assigned a severity (BLOCKING, STANDARD, INCONSISTENCY, CONFLICT)
- [ ] Every finding assigned a confidence tier (HIGH, MEDIUM, LOW)
- [ ] Repeated violations of the same checklist point collapsed with counts
- [ ] Every false-positive guard applied in order, with the discarded-candidate count recorded
- [ ] Citation verification run against every finding, with the checklist quote and source quote confirmed
- [ ] Every finding whose quote or line failed citation verification deleted rather than repaired
- [ ] Adversarial refutation run against every BLOCKING and CONFLICT finding, in fresh sub-agents
- [ ] Every refuted finding discarded, and the confirmed and refuted counts recorded
- [ ] Step 9 coverage ledger assembled, carrying files in scope, files audited, and files skipped by path
- [ ] Every file in scope either swept or recorded as UNAUDITED, with any other skip carrying one of the four
      permitted reasons (user narrowing, no binding row, generated file, unreadable file)
- [ ] Ledger states the sub-agent and batch count, the gates that ran, and the gates that failed to run
- [ ] Ledger states the layout pass status, and the revision whenever the scope was narrowed to a change set
- [ ] Ledger states the symbol usage pass status with the declaration and reference counts it reconciled
- [ ] Triage header present, carrying the severity by confidence counts and every discard count
- [ ] Every confidence tier reported, with LOW included unless the user narrowed the report
- [ ] LOW confidence findings placed in the trailing appendix rather than interleaved
- [ ] No compliant items appear in the report
- [ ] No factual errors, missing content, or source mismatches appear (those belong to /audit-facts)
- [ ] No findings invented outside the loaded checklists
- [ ] No exemption applied without a verbatim clause from a loaded skill quoted beside it
- [ ] No finding spared for shared corpus, house convention, sibling-repository text, or age
- [ ] Findings ordered: BLOCKING -> INCONSISTENCY -> CONFLICT -> STANDARD
- [ ] Cross-skill conflicts surfaced rather than silently resolved
- [ ] Fix bullets are concrete textual edits, described rather than applied
- [ ] Every fix that removes a symbol, an export entry, or a public name names that break in its Impact
- [ ] Every finding uses the shared shape, carrying a stable ID, a rank, a location line, and the Wrong, Fix, and
      Impact bullets
- [ ] Every Impact bullet names what the fix alters for callers and downstream, or states None
- [ ] A Choice bullet appears only where the audit cannot settle the question, and it closes with a recommendation
- [ ] Every sentence the report itself writes, outside a verbatim quote, is under 40 words and uses only full
      stops and commas as clause separators
- [ ] Report prose fills each line to 120 characters, with no line ending before column 100 while its next word would
      still fit
- [ ] No file modifications made during the audit