Skip to content

katopz/katgpt-rs / .agents/skills/build-hygiene

build-hygiene

Verified

Generic 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:

ProfilePurposeKey rows
[profile.dev.package."*"]deps fast, own code debuggableopt-level = 3, debug = false — * never touches workspace members
[profile.dev]the daily builddebug = "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 hatchinherits = "dev", debug = true — consumed by the rust-developer skill §8 one-attach lldb lane
[profile.gate]multi-posture CI/guard runsinherits = "dev", incremental = false; deps at opt-level = 0 in ONE shared cache instead of dozens of opt-3 dep copies
[profile.dist]shipped binariesinherits = "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 --release stays untouched — benches and dev runs compare against it; a release-profile tweak is a measurement-lane change with its own bench.
  • incremental = false for 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+cos merging into a platform sincos at 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_assertions is ON in dev — a dev-profile latency number is not a release claim.

2. The dev-loop ladder (pick by need, measure before adopting)

  1. Plain cargo dev — the baseline. Playable/fast because deps ride opt-3 while your crates stay debuggable.
  2. Dynamic-link the heavy framework deps — e.g. bevy/dynamic_linking behind 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 needs DYLD_FALLBACK_LIBRARY_PATH=<target>/debug/deps:$(rustc --print target-libdir) passed as a VAR PREFIX (macOS strips DYLD_* through the SIP-protected /usr/bin/env — measured; the env VAR=… cmd route refuses).
  3. 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 check cannot 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.
  4. 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.
  5. 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_DIR env (per-lane isolated store; NEVER blanket kache init on dev boxes; install needs BOTH kache + kache-engine). Verdict-bearing gates run KACHE_DISABLED=1 and their provenance names the kache state — and T0's disclosed delta: even disabled strips -C incremental + sets child CARGO_INCREMENTAL=0 (KACHE_PRESERVE_INCREMENTAL=1 restores 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 gate profile (one shared opt-0 dep tree) + incremental = false. Reclamation is a separate approved step — never delete target/release anywhere, never delete a tool binary's release dir that symlinks or scripts point at.
  • Per-package incremental = false on 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 with lto = "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's incremental = false for 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 prints ok. 0 passed, exit 0 — byte-identical to a pass. required-features rows protect the reader. After any clean clippy sweep, check the blind spot: which gated targets did the sweep never compile? (the cargo refine --oracle-census report does this where the rulewright is installed; otherwise grep your own [[test]]/[[bench]] rows).
  • A wrong required-features row is worse than a missing one — cargo test --workspace silently SKIPS the target; only --all-features builds it. Audit suspect rows by building them at their own feature set.
  • cargo check is not a compile-time probe — time the thing you ship: the repo's quick gate layers, or a named cargo 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-path outside 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 dist profile; verify size claims against target/dist/<bin>, never target/release/.
  • strip = true in the profile beats post-hoc strip invocations — 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)

  1. Fix mechanical lints FIRST — cargo refine --fix where the workspace rulewright is installed (compile-gated writes: --fix --write --verify, and --verify-args "--features <set>" for gated code), else cargo clippy --fix. A perf number taken over lint noise is not comparable to a clean baseline.
  2. 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.
  3. 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.
  4. 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.
  5. 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.toml comments 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).
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall