agentleFS
Sign inStart free
kekzlkekzl/imp/.claude/skills/codebase-audit/SKILL.md

codebase-audit

Skill77 starsChanged 5 days agoMITView on GitHub

Structural debt, dead code, god files, duplication, flag sprawl, whether a cleanup is worth shipping - "tech debt", "should we split this file", "remove this flag", "file size gate red", "alloc sites gate red". Not build/test (building-and-testing), perf/kernels (benchmark-cuda, sm120-cuda-expert), output quality (check-degeneration).

28 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use cloud-api-recipe-authoring, codebuddy-ide-mcp-upgrade 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.
  • TencentCloudBaseSkill

    cloud-api-recipe-authoring

    Author or revise a cloud-api-operations recipe (config/source/skills/cloud-api-operations/references/recipes/). Encodes why the long tail of control-plane capabilities is deliberately NOT wrapped as MCP/CLI tools, the API-first admission test for whether a capability deserves a recipe, the negative and positive lists, the fixed recipe structure, the writing rules distilled from writing-for-agents, the user-facing copy red lines, and the product regeneration/verification pipeline. Also routes contributors (and their agents) to the contribution flow and the pre-PR self-test protocol in references/contributing.md. Use when adding a recipe, judging whether a scenario belongs in the recipe set, updating the recipes index, re-checking existing recipes against the admission test, or onboarding someone who wants to submit one.

    Also in 3 projects that use this

  • TencentCloudBaseSkill

    codebuddy-ide-mcp-upgrade

    升级 CodeBuddy IDE（genie 扩展）内置的 CloudBase MCP，以及 MCP 发版时同步 IDE 侧白名单。当用户提到「更新 IDE 里的 MCP」「内置 MCP 版本太老」「IDE 集成的 CloudBase 功能不足」「改工具白名单 toolWhiteList」「把新 bundle 打进 CodeBuddy」「白名单漂移」「MCP 发版要同步什么」时使用。覆盖：解包定位内置 bundle 与内嵌配置、重新构建 mcp bundle、生成新的工具白名单与系统提示词、安全注入 IDE 并备份、用 MCP 协议验证工具清单、人工端到端验收、一键回滚。

    Also in 3 projects that use this

  • frostneySkill

    native-nostalgia-stack

    Applies the user's FreePascal toolchain and its build, formatting, hook, and test contracts while leaving project-specific mechanics local. Use when scaffolding or working in a FreePascal project that follows this toolchain.

    Also in 3 projects that use this

  • frostneySkill

    software-engineering-excellence

    Applies the user's engineering standards during substantial technical work: preserve scope, use current evidence, delegate independent parts, and complete authorized outcomes. Use during substantial implementation, debugging, refactoring, or multi-part delivery work.

    Also in 3 projects that use this

  • withpiperSkill

    roadmap-review

    Audit roadmap health — issues, dependency order, spec coverage, doc freshness. Use when speccing a new initiative. Use when /phase-plan output looks suspicious. Use before /roadmap-create reruns.

    Also in 3 projects that use this

  • zaxbysauceSkill

    pr-review-fix

    Codex adapter for addressing pull request review feedback in opencode-swarm. Use when the user asks to fix PR review comments, requested changes, reviewer findings, CI-review notes, or a pasted review summary with low false-positive tolerance.

    Also in 3 projects that use this

  • +6 more from TencentCloudBase

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 28 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Verify each with the recipes.

    line 31
  2. Very specific:

    Write up: dated ledger in docs/audit/ (DEBT_LEDGER_2026_08_21.md, AUDIT_ARCH_2026_07_29.md.

    line 32

“Common” is measured: kept by at least 6 in 10 of the 28 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

Codebase audit & structural debt - imp

Two hard rules

  1. A raw finding is a candidate. Fan-out sweeps over-flag: on 2026-06-09 findings C1/C2/C4 were all REFUTED on inspection and several "dead flags/files" were live. Verify each against the code before reporting; the value is in the verification.
  2. Read docs/audit/SETTLED.md BEFORE generating hypotheses. The 2026-07-29 audit generated first: 8 of 13 hypotheses were already-collapsed duplication (its section 15) and 5 facts in its own brief were stale (9 vs 16 architectures, C++20 vs C++23, src/graph/ vs src/exec/; section 19). A candidate that contradicts a ledger entry needs that entry's ANCHOR disproven. Closing a finding updates BOTH the report status line and the ledger (scripts/check-release.sh section 1d fails CI on a stale open entry; F-6, S-10 ("still open" two days after #1209) and section G each went stale for days in the 07-29 campaign).

Verification recipes

ClaimCheckTrap that fooled a past audit
flag/symbol X is deadrg across src/ tests/ tools/dump_tokens, force_bos, bench.generate looked dead in src/, read in tools/imp-cli/main.cpp
config field never readgrep the leaf for a value-read in a conditional, excluding decl/parse/copya local var with the field's name hid the read (fp8_auto_legacy)
kernel/function deadtrace the call graph, not <<< sites; code-graph has NO launch edges right now (ccg enrich broken) so rg the launcherq4k_imma CACHE was dead; mmq_q4k_imma_tile/_reorder live via q4k_imma_prefill -> mmq_q4k_imma_gemm; only ~30 LOC dead, not "~1200"
env var deadgrep docker-entrypoint.sh tooIMP_KV_FP8 read nowhere in src/, translated by the entrypoint into --kv-fp8
god-file, split itsplit on conflation or compile-time isolation, not sizegdn.cu, gemm.cu, json_schema.cpp are one domain each; the 7 attention_paged* share attention_paged_common.cuh. Precedent: engine_scheduler.cpp 2230 -> 1291 + engine_prefill.cpp + engine_decode_pipeline.cpp (#1782); gdn_scan_chunkpar.cu -> K1 + gdn_scan_chunkpar_pass.cu + .cuh at the 600-LOC kernel line; sampling family -> executor_sampling.cu (#1790); smallm -> executor_gemm_smallm.cpp (#1793)
rewrite into a registry/templateneed a concrete bugthe weight_map.cpp if (!matched) ladder is readable; a mis-mapped name = garbage output
imp.conf key inertread in src/ AND tools/? C-API bridge at engine init?server.prefix_cache was parsed, unread, bridged (#636)
a log line proves the code pathcompare the printed number against the code that uses ita CORRECT log line named a number the code did not use (#1746/#1705); the sparse startup line printed the 16-block arithmetic while ACTIVE printed the real one (#1819)
a number in a .cu is wrongpull the arithmetic into a pure function + CPU tests at both operating pointssrc/exec/sparse_attn_geometry.h, 7 tests, 4 fail on the original defect (#1819)

Workflow

  1. Ledger first: docs/audit/SETTLED.md; memory axis: root AUDIT.md; structural: docs/audit/DEBT_LEDGER_2026_08_21.md (stale [allow] reasons, the "every gate is advisory" prehistory of the blocking gates). Re-derive every brief fact (SETTLED section F lists the five that were wrong, each with a counter-check).
  2. Fan out (Explore agents, grep) AGAINST the ledger.
  3. Verify each with the recipes; demote refuted ones immediately.
  4. Write up: dated ledger in docs/audit/ (DEBT_LEDGER_2026_08_21.md, AUDIT_ARCH_2026_07_29.md; older structural_debt_* in docs/archive/), append refutations with anchors to SETTLED.md ("Refuted (do not re-chase)"); memory findings go to root AUDIT.md (CONFIRMED / REFUTED / OPEN). Counts are evidence, not estimates.
  5. Ship as small PRs off origin/main, make build + make test-unit + hooks (skill building-and-testing, shipping-prs); behavior-sensitive removals also run check-degeneration.

Gates that shape audit findings (scripts/ci_static_gates.sh; all block inside Build since #1527; hooks run them in ~2 s)

GateToolRule
File sizetools/check_filesize.py, tools/filesize_thresholds.tomlcode LOC (comments/blanks stripped): kernel .cu warn 500 / hard 600, TU 600 / 800, header 500 / 700. [allow] entries { code_loc = N, reason = "..." } are a TWO-WAY ceiling since #1526 (drift either way fails; --update re-pins). Cost metric = recompile blast radius (one .cu = one ptxas TU), so a #included .cu is charged to its includer since #1905 — executor_attention.cu read 542 as a file and 1279 as the TU. Rationale per file: docs/audit/AUDIT_FILESIZE.md. The filesize group also runs check_determinism_sites.py, check_dead_inline_accessors.py, check_log_fatal.py
Function sizetools/check_function_size.py, tools/function_size_thresholds.tomlthe largest body in a file, warn 200 / hard 500 code LOC (p99 of 5830 functions is 199). Same two-way [allow] ceiling, keyed path::signature. Exists because a file's cohesion reason was covering an 884-line function inside an allowlisted "(c) one concern" file (#1905)
Test lanestools/check_test_lanes.py --reportown check since #1770; fails on a test in no ctest entry or a unit-lane test demoted vs the base; no-lane count printed with its delta
Alloc sitestools/check_alloc_sites.py + tools/alloc_allowlist.txt, tools/check_alloc_pairs.pyinvariant I1 (one module talks to the driver); fails on a new site AND a stale entry (#1479 left gdn.cu's entry behind). Counts SOURCE sites: the T2 slot pool removed ~96% of runtime allocations with a flat site count (AUDIT.md B34); runtime number via make check-alloc-interpose (steady_state_allocations(), never benchmark that build, AUDIT.md G16)
Dead inline accessorstools/check_dead_inline_accessors.py (make check-dead-inline), tools/dead_inline_allowlist.txtheader-inline definitions with no caller
Launch guardstools/check_launch_guards.pypost-launch check present
Kernel resourcesmake kernel-resources, tools/kernel_resource_baseline.txtregister/local-frame ratchet (#1549)
Doc citationsscripts/check_doc_citations.py .a file split moves line numbers and kills file:line in living docs (#1782 -> #1783); docs/audit/ itself is exempt

Priors: settled, do not re-flag

Canonical: docs/audit/SETTLED.md (collapsed duplication S-1..S-11, deliberate specialisations, hunted-and-absent negatives, findings that were themselves wrong). Not yet in the ledger:

  • Two config systems (RuntimeConfig vs ModelConfig::Overrides) are deliberate; keys use the typed binder ladder B/I/F/S(...) (#626); the config surface lives in src/core/config/*.h.
  • Structural-debt chain D1-D4 / C1-C8 archived in docs/archive/README.md, verdicts in docs/archive/HOUSEKEEPING_2026_06_13.md. Audit #5 (docs/archive/STRUCTURAL_DEBT_2026_07_07.md, companion docs/archive/VRAM_AUDIT_2026_07_07.md): server layer is the debt source, issues #888-#897; read its NOT-flagged list first. src/memory/vram_owned.h EXISTS since #1530 (once a hallucinated finding).
  • Memory (AUDIT.md, 2026-07-29): "engine teardowns leak ~15 GiB" is REFUTED as a leak: every CUDA release works, WSL2/WDDM never returns a process's peak commitment. Traps: cudaMalloc success proves nothing (28 GiB at 22.6 GiB free; ~1530 vs ~237 GB/s tells), cudaMemPoolAttrReservedMemCurrent drops to 0 on trim, assert on UsedMemCurrent.
  • Serving-loop classes closed by measurement: host turnaround (#1791), elementwise/residual fusion (#1793), prefill||decode overlap (#1792), H2D consolidation (#1834). Roadmap item 0(c) complete.
  • A refactor that touches exec/executor.h needs a forced rebuild (grep -rl exec/executor.h src tools tests | xargs touch && make dev): stale objects segfault and look like the refactor.

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.

Check your setup, free