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.

FileKindSize
SKILL.mdskill md12.7 KB
---
name: build-hygiene
description: 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:

| 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 `--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](https://github.com/indexable-inc/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](https://github.com/kunobi-ninja/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):

```sh
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