agentleFS
jamie8johnsonjamie8johnson/cqs/.claude/skills/audit/SKILL.md

audit

Skill18 starsChanged 5 months agoMITView on GitHub

Run a multi-category code audit on the cqs codebase. Spawns parallel agents per batch.

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use delight, teach-impeccable and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • HK-hubSkill

    delight

    Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.

    Also in 31 projects that use this

  • HK-hubSkill

    teach-impeccable

    One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines.

    Also in 18 projects that use this

  • zwy123zwySkill

    normalize

    将用户随意输入的提示词规范化为结构清晰、便于大模型执行的标准化提示词。适用于需要整理、统一提示词格式时调用。

    Also in 18 projects that use this

  • ww-w-aiSkill

    pm-discovery

    PM Agent Team - Automated product discovery, strategy, and PRD generation. Runs PM analysis workflow to produce comprehensive PRD before PDCA Plan phase.

    Also in 3 projects that use this

  • ww-w-aiSkill

    qa-phase

    Run QA tests at various levels (L1-L5) for features under PDCA management. Integrates with MCP tools to execute structured test plans.

    Also in 3 projects that use this

  • +7 more from HK-hub

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. 0 are common, 12 are distinctive, and 13 are very specific to this project.

  • 0

    Common

    Most of the 173 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the 16-category code audit.

    line 10
  2. Very specific:

    Archive previous audit: If docs/audit-findings.md or docs/audit-triage.md exist, rename both with the version suffix (e.g., …

    line 52
  3. Very specific:

    Use subagent_type: "auditor" when spawning — the auditor agent definition (.claude/agents/auditor.md) has cqs tools built in

    line 72
  4. Distinctive:

    Shutdown team: after all agents complete

    line 74
  5. Very specific:

    Triage: Read docs/audit-findings.md in full, then classify:

    line 78
  6. Distinctive:

    Read the actual source file at the stated line numbers

    line 87
  7. Distinctive:

    Write a self-contained fix prompt with: exact file path, current code verbatim, replacement code, one-line "why"

    line 88
  8. Distinctive:

    Run these cqs commands before manual exploration — they surface the highest-value data in a single call.

    line 126
  9. Very specific:

    Code Quality: Run cqs dead --json + cqs health --json first.

    line 129
  10. Very specific:

    Documentation: Run cqs health --json for staleness counts.

    line 130
  11. Distinctive:

    API Design: No mandatory command.

    line 131
  12. Distinctive:

    Error Handling: No mandatory command — grep-driven.

    line 132
  13. Very specific:

    Observability: No mandatory command — grep for tracing:: patterns.

    line 133
  14. Very specific:

    Test Coverage (adversarial): Run cqs health --json first (includes untested hotspots).

    line 134
  15. Very specific:

    Robustness: No mandatory command — grep for .unwrap(), .expect(, panic!

    line 135
  16. Very specific:

    Scaling & Hardcoded Limits: No mandatory command — grep-driven (const definitions, .clamp( sites, capacity/Duration literals, dim literals).

    line 136
  17. Very specific:

    Algorithm Correctness: Use cqs explain <fn> --json on algorithmic functions.

    line 139
  18. Very specific:

    Extensibility: Run cqs health --json for hotspot overview.

    line 140
  19. Distinctive:

    Platform Behavior: No mandatory command.

    line 141
  20. Distinctive:

    Security: No mandatory command.

    line 142
  21. Distinctive:

    Data Safety: No mandatory command.

    line 143
  22. Very specific:

    Performance: Run cqs health --json first (identifies hotspots).

    line 144
  23. Distinctive:

    Resource Management: No mandatory command.

    line 145
  24. Very specific:

    Test Coverage (happy path): Run cqs health --json first (includes untested hotspots).

    line 146
  25. Distinctive:

    Stop at diminishing returns during discovery

    line 153

“Common” is measured: kept by at least 6 in 10 of the 173 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Audit

Run the 16-category code audit.

Implementation — the audit workflow (preferred)

The discovery + synthesis + disposition phases now run as one reusable workflow, .claude/workflows/audit.js:

Workflow({ name: 'audit', args: { churn: '<recently-changed areas to scrutinize>' } })
  • Discovery — all 16 categories in ONE parallel stage (auditors return structured findings; no team, no 2-batch split — the concurrency cap schedules them).
  • Synthesize — one agent dedups/clusters, triages P1–P4 (refining the deterministic difficulty×impact first-pass), assigns each row a disposition route, and WRITES docs/audit-findings.md + docs/audit-triage.md.
  • Disposition — per row: auto-fix → generate a fix-spec + adversarially verify it against source; issue → draft a title+body; tracked/inline/drop → skip. Gen/verify/draft agents are read-only (Explore) so prepare-mode can't mutate the tree. args.implement=true additionally runs worktree-isolated implementers on verified fixes.

The orchestrator (main loop) keeps the gated acts — deliberately NOT in the workflow because they're irreversible / outward-facing / serialized to protected main:

  • Review the triage — the cornerstone P1-vs-P2 + accept/reject/route-override call.
  • /land the verified fixes (serialized, CI-gated).
  • gh issue create the drafts, after dedup against open issues.

Route by fix-nature, not tier: a high-impact finding whose fix is a judgment call (architecture/API/perf-tradeoff) is issue, never auto-fix.

The team-based process below is the legacy reference — kept for the category scopes and the fix-prompt-review detail the workflow embodies. Teams are currently unavailable, so use the workflow.

Arguments

  • $ARGUMENTS — batch number (1-2) or all for full audit

all means run BOTH batches — all 16 categories. Run batch 1, then batch 2, then triage all findings together. Do NOT stop after batch 1.

Batches

There are 16 categories split into 2 batches of 8. Each batch spawns 8 parallel agents (one per category). all runs both batches sequentially.

BatchCategories
1Code Quality, Documentation, API Design, Error Handling, Observability, Test Coverage (adversarial), Robustness, Scaling & Hardcoded Limits
2Algorithm Correctness, Extensibility, Platform Behavior, Security, Data Safety, Performance, Resource Management, Test Coverage (happy path)

Process

Setup

  1. Archive previous audit: If docs/audit-findings.md or docs/audit-triage.md exist, rename both with the version suffix (e.g., audit-findings-v0.9.1.md, audit-triage-v0.9.1.md). Each audit starts with fresh files.
  2. Enable audit mode: cqs audit-mode on --expires 2h — prevents stale notes from biasing review (no -q flag exists; the subcommand takes only on/off + --expires)

Per-Batch

  1. Create team: One team per batch (audit-batch-N)
  2. Spawn teammates: One per category. Use model: "fable" for every auditor (per the 2026-06-11 model split: review/audit-finder lanes → fable) — the 2026-06-10 review/fix campaign showed Fable at or above opus quality on exactly this kind of judgment work (15/15 review findings confirmed, premise-drift catches, empirical hypothesis correction). Sonnet produces lower-quality judgments and haiku misses subtle findings. The per-category scope keeps each agent focused enough that frontier-model cost is reasonable.

    Exception — the Security category auditor uses model: "opus". Fable's documented bug-finding gains explicitly exclude security-focused analysis (its cyber classifiers apply there), and benign-adjacent security work can occasionally trigger a classifier false positive — a mid-run refusal kills that category's coverage for the whole audit. Opus carries no refusal risk on this lane, has no documented capability deficit for it, and costs half. Same reasoning applies to /boundary-probe.

    Nested-lead option for broad categories (Code Quality, both Test Coverage categories, Performance, Data Safety): spawn the teammate as subagent_type: "general-purpose" (it needs the Agent tool) and have it (1) run the category's mandatory cqs commands itself, (2) fan out 3 read-only sub-scope agents in parallel (subagent_type: "explorer", omit model so they inherit; HARD RULE in their prompts: no file writes — return candidate findings as their final message), (3) verify every candidate against the cited source + archived triages before appending, and report the candidate→appended funnel. Measured v1.42: 38 candidates → 31 appended (1 cross-category dup caught, 5 same-root-cause merges, 1 stale-triage reject); the two nested categories produced the largest verified hauls and the most P1s. Narrow/mined-out categories (Scaling found 1 finding in v1.42) stay single-agent — the lead overhead isn't worth it.

  3. Each teammate prompt must include:
    • Their category scope (from table below)
    • Instruction to read archived triage files (e.g., docs/audit-triage-v*.md) — skip anything already triaged in prior audits
    • Instruction to read docs/audit-findings.md first — skip anything already reported by earlier batches in this audit
    • Instruction to append findings to docs/audit-findings.md via bash heredoc append (cat >> docs/audit-findings.md <<'EOF' ... EOF) — never Edit/Write on that file; 8 agents append concurrently and Edit fails with "file modified since read". This replaces the old per-category scratch-file + aggregation step: v1.42 ran 8 concurrent heredoc appenders with zero conflicts. (Initialize the findings file with a header before spawning so appends have a base.)
    • Format: ## [Category]\n\n#### [Finding title]\n- **Difficulty:** easy | medium | hard\n- **Location:** ...\n- **Description:** ...\n- **Suggested fix:** ...
    • Use subagent_type: "auditor" when spawning — the auditor agent definition (.claude/agents/auditor.md) has cqs tools built in
  4. Shutdown team after all agents complete

After All Batches

  1. Triage: Read docs/audit-findings.md in full, then classify:
    • P1: Easy + high impact → fix immediately
    • P2: Medium effort + high impact → fix in batch
    • P3: Easy + low impact → fix if time
    • P4: Hard or low impact → create issues for hard items; fix trivial ones inline (doc comments, one-liners, undocumented edge cases)
    • Write triage to docs/audit-triage.md — fresh file with P1-P4 tables (include Status column). This survives context compaction.
    • Carry forward prior-triage open items: read the most recent archived triage (docs/audit-triage-v*.md, honoring any verification section that supersedes its row statuses), reconcile against PRs merged since, spot-grep ambiguous items against main, and append the still-open entries as CF-P2/CF-P3 tables. The live docs/audit-triage.md must be the single source of truth for everything open — no hunting through archives.
  2. Generate fix prompts: For each P1, P2, and P3 finding, spawn fable agents to (P4 trivials get prompts too; hard P4s get issue descriptions):
    • Read the actual source file at the stated line numbers
    • Write a self-contained fix prompt with: exact file path, current code verbatim, replacement code, one-line "why"
    • Group related findings (e.g., stale doc references) into a single prompt
    • Save to docs/audit-fix-prompts.md
  3. Review fix prompts: Spawn a second fable agent to verify each prompt against the actual source:
    • Does the "current code" match what's really in the file? (catches line drift)
    • Does the fix compile? (check types, imports, API existence)
    • Are there any missing edge cases?
    • Report: "VERIFIED" or "NEEDS FIX — [specific issue]"
    • This step catches 20-40% of prompt errors (wrong field names, nonexistent APIs, moved code) — measured NEEDS-FIX rates: P1 42%, P2 41%, P3 16%
  4. Execute fixes: P1 first, then P2. Dispatch opus implementer agents for the fixes (implementation lane); keep verification/review agents on fable. Mark each item in triage as fixed.
  5. Disable audit mode: cqs audit-mode off

Category Scopes

CategoryCovers (merged from)
Code QualityDead code, duplication, complexity, coupling, cohesion, module boundaries, convenience wrappers that hardcode defaults
DocumentationAccuracy, completeness, staleness of docs and comments
API DesignConsistency, ergonomics, naming, type design
Error HandlingResult chains, context, recovery, swallowed errors
ObservabilityLogging coverage, tracing, debuggability
Test Coverage (adversarial)Edge-case/sad-path gaps: malformed input, NaN/Inf embeddings, concurrent access, empty queries, huge inputs, error paths not tested
Test Coverage (happy path)Missing tests for high-caller public functions, untested modules, integration test gaps, meaningful assertion quality
Scaling & Hardcoded LimitsConstants that should scale with model config, corpus size, or hardware. Magic numbers without rationale.
Robustnessunwrap/expect, edge cases (empty/huge/unicode/malformed), panic paths
Algorithm CorrectnessOff-by-one, boundary conditions, logic errors
ExtensibilityAdding features without surgery, hardcoded values
Platform BehaviorOS differences, path handling, WSL quirks
SecurityInjection, path traversal, file permissions, secrets, access control
Data SafetyCorruption, validation, migrations, races, deadlocks, thread safety
PerformanceO(n²), unnecessary iterations, batching, caching, I/O patterns
Resource ManagementMemory usage, startup time, idle cost, OOM protection, leaks

Mandatory First Steps per Category

Run these cqs commands before manual exploration — they surface the highest-value data in a single call.

Batch 1:

  • Code Quality: Run cqs dead --json + cqs health --json first. Also grep for convenience wrappers that hardcode defaults (e.g., fn foo() that calls foo_with_dim(HARDCODED)) — these mask incorrect wiring when the default changes.
  • Documentation: Run cqs health --json for staleness counts.
  • API Design: No mandatory command.
  • Error Handling: No mandatory command — grep-driven.
  • Observability: No mandatory command — grep for tracing:: patterns.
  • Test Coverage (adversarial): Run cqs health --json first (includes untested hotspots). Check for adversarial test gaps: functions that accept user input, external data, or embeddings should have tests for malformed/adversarial inputs (empty, NaN, truncated, wrong-type, concurrent).
  • Robustness: No mandatory command — grep for .unwrap(), .expect(, panic!.
  • Scaling & Hardcoded Limits: No mandatory command — grep-driven (const definitions, .clamp( sites, capacity/Duration literals, dim literals).

Batch 2:

  • Algorithm Correctness: Use cqs explain <fn> --json on algorithmic functions.
  • Extensibility: Run cqs health --json for hotspot overview.
  • Platform Behavior: No mandatory command.
  • Security: No mandatory command.
  • Data Safety: No mandatory command.
  • Performance: Run cqs health --json first (identifies hotspots).
  • Resource Management: No mandatory command.
  • Test Coverage (happy path): Run cqs health --json first (includes untested hotspots).

Rules

  • Collect ALL findings before fixing ANY
  • One batch at a time (context limits)
  • Clean up teams between batches
  • Stop at diminishing returns during discovery
  • Once triaged, complete the tier — don't suggest stopping mid-priority
  • Cross-check findings against open GitHub issues — note overlaps as "existing #NNN"
  • Mark items in docs/audit-triage.md as fixed when done — update the Status column (e.g., ✅ PR #N or ✅ fixed). This is the source of truth for what's been addressed.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.