git:20260811.89ad6e1 to git:20260901.a877ac0

- description: Audits the smallest relevant developer-facing surface of a library, CLI, SDK, or npm package across API contracts, errors, CLI behavior, public types, onboarding, and config. Uses candidate-first rule loading, bounded local evidence, and compact root-cause findings. Use when asked to "audit my CLI", "make this CLI agent-friendly", "is this API ergonomic", "review the developer experience", "improve these errors", "simplify first run", or "review my SDK". For end-user UI use ui-design Audit mode, for agentic-app trust use ax-audit, for docs prose use docs-writing, for README work use readme-creator, and for repo architecture use codebase-architecture. Inside a product that also ships a UI, this is the skill for the developer-facing half, so pick it when the complaint is about an import, command, error string, exported type, or config rather than a screen.

- - **IS:** a bounded review of public APIs, developer-facing errors, CLI commands, exported types,

- install and first-run behavior, and config.

- - **IS NOT:** a repo-wide quality sweep, end-user UI audit (`ui-design` Audit mode), agent trust review

- (`ax-audit`), prose rewrite (`docs-writing`), README rewrite (`readme-creator`), or repository

- architecture review (`codebase-architecture`).

-

- ## Modes and scope lock

- Choose the narrowest mode supported by the request:

- 1. **Targeted audit (default):** inspect the named surface or changed public surface and report.

- 2. **Fix:** only when the user asks to fix, improve, simplify, or implement; make localized fixes

- inside the locked scope, then verify them.

- 3. **Exhaustive:** only when the user explicitly asks for the whole package or every public surface.

- Before exploration, write a one-line scope receipt:

- Scope: <mode>; surfaces: <commands/exports/config>; prefixes: <err-, cli->; excludes: <UI/docs/architecture/private internals>

- If several skills are invoked, keep only the developer-facing surfaces above. Let sibling skills

- own their areas without duplicating their search or findings. "DX", "gold standard", and "review

- holistically" do not by themselves authorize a multi-repo or whole-package sweep.

- - [ ] 1. Lock intent, public surfaces, and exclusions

- - [ ] 2. Trace the minimum local evidence path

- - [ ] 3. Select prefixes and candidate rule files

- - [ ] 4. Confirm and rank material findings

- - [ ] 5. Report, or fix only when requested

- - [ ] 6. Re-run the same checks and record evidence

- Default to `git diff` against the repository's normal base, then keep only changed files reachable

- through a public entry point. With no useful diff, use the command, export, package, error, or config

- named by the user.

-

- Public reachability comes from evidence such as `package.json` `exports`/`bin`, a command registry,

- an exported type, a documented config loader, or an observed error path. Do not audit a private

- helper unless a public caller exposes its behavior.

-

- ### 2. Follow the evidence ladder, then stop

- Take these rungs in order:

- 1. Read local instructions, the relevant manifest, and the diff or named entry point.

- 2. Trace only direct public dependencies and the nearest tests that establish behavior.

- 3. For a CLI, use a small safe probe set when useful: `--help`, `--version`, one success path, and

- one invalid-input path. Do not trigger a real mutation merely to test DX.

- 4. Check a prior release contract only when the diff changes a public export, signature, or return

- shape.

- Stop when the behavior is proven, disproven, private, or outside scope. Do not browse general best

- practice articles, inventory unrelated apps, build static repo maps, or spawn overlapping scouts.

- External research is for an explicit comparison request or a named uncertainty local evidence

- cannot resolve. In an explicit exhaustive audit, parallel work may partition disjoint public

- surfaces; it must not run several generic whole-repo reviews.

- Read `rules/_sections.md`, then select only prefixes applicable to the locked surface:

- | 3 | `cli-` | CLI UX | HIGH | 13 |

- | 5 | `onboard-` | Install and first run | HIGH | 4 |

- Map surfaces to prefixes: a public API entry point uses `api-`, `types-`, and reached `err-`

- paths; a CLI uses `cli-` and reached `err-` paths; exported declarations use `types-`, plus

- `api-` only when behavior changes; install and first run use `onboard-`; config loaders use

- `config-` and reached `err-` paths.

-

- Applicability outranks global priority. A CLI-only audit runs applicable `err-` rules before

- `cli-`; it does not load `api-` merely because API rules have higher impact.

-

- For a targeted audit:

- 1. List filenames for the selected prefixes; their names form the candidate checklist.

- 2. Inspect the scoped behavior for concrete candidate evidence.

- 3. Open only the exact candidate rule files needed to confirm or reject a finding.

- 4. Cite a rule id only after reading that file. Never invent one from memory.

- For an explicit exhaustive audit, read every rule in the selected prefixes. Read

- `references/dx-principles.md` only when the user asks for rationale or a borderline finding needs a

- tie-breaker. Read `rules/_template.md` only when adding or editing a rule.

- Capability-gate candidate rules even inside a selected prefix:

- - Structured JSON input and schema introspection apply when automation or agent use is promised,

- requested, or already supported.

- - Dry-run and confirmation apply to destructive, expensive, or difficult-to-reverse mutations.

- - Progress, delta polling, and resume apply to operations that can block, outlive one command, or

- be retried after ambiguous output.

- - CRITICAL findings first, then HIGH, then MEDIUM using each rule's frontmatter impact.

- - Copy the rule's frontmatter impact exactly. Impact is the rule's declared consequence, not a

- confidence score; never downgrade it because the local instance feels minor.

- - Merge repeated instances of one root cause into one finding with up to three representative

- locations.

- - Do not flag a hypothetical missing feature with no current consumer path. YAGNI is not a defect.

- - Do not turn absence of JSDoc, error codes, or a flag into one finding per symbol or command.

- - In targeted mode, report all CRITICAL findings, then the highest-value remaining findings up to

- five total. Summarize any remainder by category rather than expanding the audit.

- - Before reporting, compare every cited rule id with the rule files actually opened. Open any

- missing file and use its frontmatter impact, or remove the citation.

- Audit-only requests are read-only. A request to improve or fix authorizes localized changes inside

- the scope receipt, not a redesign of adjacent docs, UI, or architecture.

-

- Use this compact output:

- Only list files with findings. If none are material, return one pass line naming the surfaces and

- rule files checked. Do not emit a `✓ pass` entry for every clean file or repeat a DX principle under

- every finding. In exhaustive mode, include every material finding; list clean files only when the

- user requests compliance-style evidence.

-

- For fix mode, replace `Deferred` with `Changed` and `Verification`, including the exact commands or

- runtime probes that passed.

-

- Before sending the report, check:

-

- ```text

- Report preflight:

- - every cited rule file was opened

- - every [IMPACT] exactly matches that file's frontmatter

- - the inspected-file count matches the unique files named

- - no out-of-scope or per-clean-file filler entered the report

- ```

- Re-open every touched or cited location, rerun the same safe probes and focused project checks, and

- reapply the same candidate rules. A clean build alone does not prove CLI behavior; a runtime probe

- alone does not prove exported types. Verification evidence must match the finding.

- | `rules/<prefix>-*.md` | A targeted candidate exists, or the user requests exhaustive coverage |

- | `references/dx-principles.md` | Rationale is requested or a finding is borderline |

- | `references/evaluation-scenarios.md` | Evaluating or changing this skill's workflow |

- - **Probe the local build, not the published binary.** `npx <pkg>` and an existing global install

- both resolve the registry copy, so `--help`, exit codes, and error strings describe a release the

- working tree has not changed. Build, then invoke the local entry point (`node ./dist/cli.js`).

- - `ax-audit`: agentic application architecture and trust

- - `codebase-architecture`: repository structure, module contracts, and the guardrails inside the repo, rather than the surface a package ships outward