cs-audit

cs-audit

Required reading before starting

Before any judgment or action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute by reading external AI entry points (see .codestable/reference/execution-conventions.md）。

cs-issue waits for you to report a bug,cs-refactor waits for you to point out an optimization,cs-keep waits for you to say "make a note of this"—but the request "I don't even know what's wrong, just scan through it and take a look" has no one to handle it.cs-audit fills this gap:Proactively scan within the scope defined by the user, and produce a findings list cross-classified by severity × nature。

This skill only discovers, it does not decide on fixes. Fixing is the job of cs-issue / cs-refactor .

Where to put the file

.codestable/audits/{YYYY-MM-DD}-{slug}/
├── index.md           # 速览：范围、总评、发现清单交叉矩阵
├── finding-01.md
├── finding-02.md
└── ...

The date is the audit date. The slug should be short enough to see the audit target at a glance (auth-module、order-flow、payment-security）。

All audit documents carry YAML frontmatter (doc_type are respectively audit-index and audit-finding) to facilitate search-yaml.py retrieval.

Dimension matrix (cross-classification)

Each finding gets two tags:

Nature：bug | security | performance | maintainability | arch-drift

Severity：P0(must fix) | P1(should fix) | P2(could fix)

Cross examples:

security × P0: SQL injection, storing passwords in plaintext
bug × P1: null pointer under specific boundary conditions, actual trigger probability is low
performance × P2: redundant object allocations inside a loop, only needs changing on hot paths

In addition, each finding carries confidence（high / medium / low) andsuggested action（cs-issue / cs-refactor）。

For the complete template see reference.md。

Workflow

Phase 1: Scope convergence

An audit cannot blindly scan the entire repository—the cost is high and the noise is large. First help the user narrow the scope to something executable.

Ask the user for three things (any one is enough to get started):

Keywords: "related to auth / payment / upload"
Module / directory："src/services/ under"
A paragraph of description: "Recently users reported the order page is slow, help me scan the order-related code"

If the user's description is already clear, go directly to Phase 2. If the user says "scan the whole project" → push back—suggest first scanning the modules that change most often or the areas that have had problems recently.

After convergence, confirm with the user:"Scan src/services/order/ and src/api/order.ts, about 12 files, looking at the three dimensions of security / performance / bug risks. Is the scope OK?"

Phase 2: Scan

Scan dimension by dimension according to the dimensions the user has circled (if the user did not specify, scan all 5 dimensions):

bug risks: null paths, missing boundary conditions, race conditions, error handling that swallows exceptions, unprotected type assertions
Security: injection risks, exposure of sensitive data, missing permission checks, insecure dependencies
Performance: N+1 queries, repeated computation, uncached hot paths, memory leaks, full loads without pagination
Maintainability: overly long functions (> 80 lines), cyclomatic complexity > 15, duplicated logic blocks, magic constants, circular dependencies
Architecture deviation: code violates decisions already finalized in .codestable/requirements/adrs/ , layering leaks, implicit cross-module coupling

During scanning, use Glob / Grep / Read to actually read the code. Every finding must record 文件:行号 + a specific code snippet.

Upper limit: report at most 5 items per dimension. It's not about padding the count—stop when there's enough, and don't force it when there isn't.

Confidence criteria：

high: the code path can be confirmed to trigger, and the impact is clear
medium: static analysis can locate the problem, but the trigger conditions are uncertain
low: the clue is suspicious and needs further confirmation but is worth flagging

Phase 3: Rating + Output

Assign nature + severity + confidence + recommended action to each finding
Write index.md: scope, overall assessment, findings list table (cross-classification)
Write each finding individually finding-NN.md

Write index first, then findings—this order lets the AI make an overall judgment first and then expand into details, avoiding getting lost in a single finding and losing sight of the whole.

Phase 4: Recommend next steps

Give priority recommendations at the end of index.md:

"Open issues and fix the 3 P0 items immediately"
"The 5 P1 items can be scheduled for the next iteration"
"The 4 P2 items can be looked at when there's time"

Whichever one the user chooses → route to cs-issue or cs-refactor。cs-audit does not fix it itself.

Boundaries with adjacent skills

Skill	Trigger	How cs-audit treats it
`cs-issue`	User reports a known bug	After audit finds a bug, recommend opening `cs-issue`
`cs-refactor`	User points out a known optimization point	After audit finds an optimization point, recommend opening `cs-refactor`
`cs-keep`	Capture single-point experience / decisions	audit scans multiple dimensions in batch to discover new problems; cs-keep writes down what is already known
`cs-domain`	Maintain ADR / CONTEXT.md	cs-domain writes decisions; cs-audit checks whether the code deviates from ADRs that have already been decided
`cs-security-review`	Security review	audit's security dimension is a lightweight scan; in-depth security review goes through a specialized track

Guardrails

Do not blindly scan the entire repository—Phase 1 must narrow the scope; do not start without a scope
Every finding must have evidence—file:line + code snippet + why it constitutes a problem. Findings without evidence such as "feels bad" or "might have a problem" are not allowed
Confidence must be marked—do not mark all findings as high
At most 5 items per dimension—force the AI to pick the ones most worth reporting, not dump all findings
Only discover, do not fix—cs-audit does not produce code changes. If "fixed it along the way" appears, that counts as overstepping
Architecture deviation cites ADR—do not judge from memory what the architecture should look like; you must read .codestable/requirements/adrs/ for comparison
Old audits are marked as outdated—when a new audit of a module with the same name covers an old audit, mark the old index status: superseded + superseded-by: {新目录}

Exit conditions

The audit scope has been confirmed with the user
Scanning of all dimensions is complete, with at least one finding (if zero findings: inform the user that no obvious problems were found within this scope)
index.md contains a complete cross-classification table
Every finding has file:line + evidence + confidence
At most 5 items per dimension
Provide the user with next-step recommendations arranged by priority

About this skill