katopz/katgpt-rs / .agents/skills/build-hygiene
build-hygiene
VerifiedGeneric Rust build-hygiene gate for compile time, binary size and the dev-edit loop. Use when adding deps or features or crates, touching cargo profiles, when a build/link/boot loop feels slow, when target dirs bloat, when choosing a dev-loop driver (plain cargo vs framework dynamic-linking vs blaze), before quoting any build-time or size or perf number, or quarterly as a hygiene pass. Enforces the profile discipline (dev line-tables-only + opt-3 deps, a shared opt-0 gate tree, dist fat-LTO strip), the determinism law against profile pins, isolated target dirs, the pre-registered A/B bar, and lint-fixing before any perf claim.
build-hygiene
Compile time, binary size, and the dev-edit loop are MEASURED postures, not vibes.
This skill is the workspace-agnostic discipline; where a repo documents its own
[profile] rows in Cargo.toml comments, those comments are the canonical text
and this skill defers to them.
1. The profile discipline
The canonical five-profile shape for a workspace that runs many build postures (heavy test/guard matrices) and ships a real-time binary:
| Profile | Purpose | Key rows |
|---|---|---|
[profile.dev.package."*"] | deps fast, own code debuggable | opt-level = 3, debug = false — * never touches workspace members |
[profile.dev] | the daily build | debug = "line-tables-only" — the EXPLICIT string spelling, never debug = 1; backtraces keep file/line, debugger locals are the deliberate loss |
[profile.dev-full] | the debugger escape hatch | inherits = "dev", debug = true — consumed by the rust-developer skill §8 one-attach lldb lane |
[profile.gate] | multi-posture CI/guard runs | inherits = "dev", incremental = false; deps at opt-level = 0 in ONE shared cache instead of dozens of opt-3 dep copies |
[profile.dist] | shipped binaries | inherits = "release", opt-level = 3 (never "s" on a real-time renderer), lto = "fat", codegen-units = 1, strip = true |
Measured shape of the win (one Apple-M3-Max game workspace, 2026-10): deps-at-opt-3
dev made the mid-loop edit→linked-binary ~4.9 s against ~22.7 s in release; moving a
~40-posture guard matrix onto one shared opt-0 gate tree bounded a target dir that had
grown past 133 GB; the workspace line-tables-only change is what made every
per-posture build affordable.
Rules:
- Plain
--releasestays untouched — benches and dev runs compare against it; a release-profile tweak is a measurement-lane change with its own bench. incremental = falsefor single-pass postures — a posture that compiles exactly once per run gains nothing from incremental caches, and they cost tens of GB of.rcgu.o.- THE DETERMINISM LAW (hard rule). A golden/fixture that forks across opt
levels is a determinism defect in the code — e.g. libm
sin+cosmerging into a platformsincosat opt ≥ 1 can move results by 1 ULP — fix the math with a deterministic implementation (a pure-Rust trig, an integer path, a pinned reduction order). NEVER resurrect[profile.dev.package.*]opt-0 pins to mask the fork; a pin taxes every future dev loop and hides the defect. - The profile is part of every claim. A timing or size number names its
profile and feature set;
debug_assertionsis ON in dev — a dev-profile latency number is not a release claim.
2. The dev-loop ladder (pick by need, measure before adopting)
- Plain cargo dev — the baseline. Playable/fast because deps ride opt-3 while your crates stay debuggable.
- Dynamic-link the heavy framework deps — e.g.
bevy/dynamic_linkingbehind an opt-in dev-only feature. Expect roughly a 20%+ cut in edit-to-frame, biggest on cross-crate edits (the worst case is exactly where linking dominates). Conditions, all of them: DEV-LOOP ONLY · never in a default feature set · never in a receipt or shipped/release lane · on macOS a dylib-linked binary needsDYLD_FALLBACK_LIBRARY_PATH=<target>/debug/deps:$(rustc --print target-libdir)passed as a VAR PREFIX (macOS stripsDYLD_*through the SIP-protected/usr/bin/env— measured; theenv VAR=… cmdroute refuses). - blaze — an external incremental
daemon (rust-analyzer/MIR + Cranelift; patches changed functions into the
already-built binary; claims ~10× warm-edit builds with honest per-project
tables). Facts that gate adoption: it builds with its OWN toolchain (a dated
nightly, whatever your repo pins), trades GB-scale memory, and is young —
cargo + CI stay the final word. Adopt only through a measured pilot on your
own loop, never on published numbers alone.
Not a rung: toolchain-replacing JIT runtimes. makepad/relax replaces
rustc/LLVM/the linker entirely (its own borrow checker + backends, interp→O1→O3
tiering) — a faster "compiler" that ISN'T your compiler: a JIT run sits outside
every pinned-toolchain gate (rust-toolchain.toml, determinism pins, wasm lanes,
CI), its
checkcannot substitute for a rustc-semantic gate (proven semantic divergences exist), and ecosystem compat (bevy/egui/wgpu) is unproven. Distilled MARGINAL 2026-11-12 (riir-refine queue, pin 23d69916) — pilot-only if ever, and not worth the pilot on a bevy stack today. - Measure the LOOP, not the build half. The metric is edit→first-frame
(GUI) or edit→test-green (headless): stimulus apply → incremental build →
observed result. Interleaved A→B pairs, per-arm isolated
CARGO_TARGET_DIR, per-iteration logs kept. Every timed row verifies the BINARY SHA CHANGED — a comment/mtime touch does not relink under incremental; that row is INVALID, not slow. - kache — the job-lane build cache
(ADOPTED 2026-11-16, m3 pilot bench 157 PASS: 26/26 rlib blake3-identical
across worktrees; per-added-worktree disk 92 MB → ≈0 via CoW clone restore;
warm-store new-worktree ~3.7-4.3x, warm clippy 0.02 s vs 3.4 s; dev-loop
~9%/edit → dev loops stay incumbent). JOB LANES ONLY: arm via
RUSTC_WRAPPER=kache+KACHE_CACHE_DIR/KACHE_RUNTIME_DIRenv (per-lane isolated store; NEVER blanketkache initon dev boxes; install needs BOTHkache+kache-engine). Verdict-bearing gates runKACHE_DISABLED=1and their provenance names the kache state — and T0's disclosed delta: even disabled strips-C incremental+ sets childCARGO_INCREMENTAL=0(KACHE_PRESERVE_INCREMENTAL=1restores parity), so wrapper-REMOVAL (env unset) is the byte-incumbent path, not disable. Armed and unarmed lanes NEVER share a target dir. Disk accounting: du lies across CoW clones — account by df +kache stats; the store is a GC-bounded regenerable class (kache clean --orphans= the dead-worktree detector); the kache CLI needs the lane's env for store-scoped reads.
3. Compile-time technique table
- Target-dir bloat is a POSTURE-COUNT problem. Dozens of postures × opt-3
dep copies = 100+ GB. Fix: the
gateprofile (one shared opt-0 dep tree) +incremental = false. Reclamation is a separate approved step — never deletetarget/releaseanywhere, never delete a tool binary's release dir that symlinks or scripts point at. - Per-package
incremental = falseon the hottest-edited crates, inside an incremental-on release profile (makepad/relax Cargo.toml, measured in-source: "a relax-compiler edit rebuilds in 33 s instead of 59 s", clean 63→52 s withlto = "off"). The counterintuitive shape: a crate edited every few minutes pays incremental-cache write/invalidate cost on every build, so fresh is faster for that crate while every other member keeps incremental. Mirror of §1'sincremental = falsefor single-pass postures — there the reason is one compile per run, here it is many compiles of one crate. - Sibling build holding the lock:
CARGO_TARGET_DIR=/tmp/<task>— never wait on a lock, never share a target tree across concurrent sessions; move scratch targets to a roomy volume when the internal disk runs low. - The green-zero trap. A whole-file
#![cfg(feature = "x")]-gated test target run without the feature printsok. 0 passed, exit 0 — byte-identical to a pass.required-featuresrows protect the reader. After any clean clippy sweep, check the blind spot: which gated targets did the sweep never compile? (thecargo refine --oracle-censusreport does this where the rulewright is installed; otherwise grep your own[[test]]/[[bench]]rows). - A wrong
required-featuresrow is worse than a missing one —cargo test --workspacesilently SKIPS the target; only--all-featuresbuilds it. Audit suspect rows by building them at their own feature set. cargo checkis not a compile-time probe — time the thing you ship: the repo's quick gate layers, or a namedcargo build --profile <p> -p <pkg>with the box quiet.- wasm/embedded lanes are optional lanes — keep their deps out of the native
default set; a union feature compiles the browser/cross lane; a manifest drift
gate (
bundle vs manifest) catches the stale-artifact class. - Workspace-excluded crates need mirrored profiles. A crate built by
--manifest-pathoutside the workspace does not inherit your[profile]rows — mirror the ones it needs, or its builds quietly regress to defaults.
4. Binary size
- Shipped = the
distprofile; verify size claims againsttarget/dist/<bin>, nevertarget/release/. strip = truein the profile beats post-hocstripinvocations — declared, reproducible, cannot be forgotten.- For leak-sensitive shipped binaries, build with
RUSTFLAGS="--remap-path-prefix $HOME=/build"(or a fixed prefix) and run a binary string-leak scan — the home path, usernames and machine names must not ship. opt-level = "s"/"z"are REFUSED on real-time renderers/servers without a measured frame-time A/B proving no regression — the frame budget wins over bytes.- Content/artifact size (compressed bundles, dataset archives) is a separate lane — compression at the artifact boundary, not profile flags.
5. The perf law (fix before you measure)
- Fix mechanical lints FIRST —
cargo refine --fixwhere the workspace rulewright is installed (compile-gated writes:--fix --write --verify, and--verify-args "--features <set>"for gated code), elsecargo clippy --fix. A perf number taken over lint noise is not comparable to a clean baseline. - Pre-register the bar BEFORE data — write the want-faster threshold and the decision rule into the plan/bench doc first; the verdict is mechanical afterwards, not narrative.
- Interleaved pairs, not sequential arms — two sequential runs measure the box's load drift (±5–22% on a shared box); interleave A→B pairs and report p50 + total + slowest.
- Box state is part of the number — quote a provenance line (power source, power mode, load, swap; GPU exclusivity for GPU gates) beside every latency figure. Say "measured faster", never a guaranteed number; a marginal margin is disclosed as marginal and re-read before anyone relies on it.
- A latency number without its box state is not a measurement — a probe run on a loaded box is evidence of nothing; re-run alone or discard.
6. The housekeeping pass
Quick pass (every housekeeping cycle, report-only):
du -sh target 2>/dev/null # per repo; report, do NOT delete
ls -la target/release/ target/dist/ 2>/dev/null | head -20 # binary sizes
grep -c "^\[profile" Cargo.toml # vs the repo's own documented set — drift is a finding
time <the repo's quick gate> # e.g. ci_feature_guard.sh --quick, or a named build
cargo refine <paths> # DRY RUN on dirty files (or: cargo clippy for the baseline)
Findings are filed, never fixed inline: a bloated target → an approved cleanup pass; a missing/drifted profile → an issue citing this skill; a binary growth
10% without a landed reason → an issue; a quick-gate time above its last recorded baseline → bisect before touching profiles.
Full pass (quarterly, or after any profile/feature-set/crate-count change):
- re-run the dev-loop A/B harness (build one before adopting any driver) and compare against the last recorded baseline;
- re-time the quick gate layers and compare against the last recorded posture;
- re-check the profiles against §1 (the repo's
Cargo.tomlcomments are the canonical text — prose drift is a finding); - verify excluded/leaf workspaces carry mirrored profiles (§3);
- verify no
DYLD/dynamic-linking posture leaked into a default set, receipt, or shipped lane (§2's conditions).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |