why-not-rust

Evidence before rewrite. A cross-agent skill for deciding whether Rust should stay out, enter at one seam, replace a component, or take over the assessed target.

Point the skill at a repository or migration RFC. It returns:

• an authorization: APPROVE / REJECT / DEFER–MEASURE;
• the smallest justified scope: STAY / EXTRACT / PARTIAL / MIGRATE;
• claim-level evidence, confidence, and decision robustness;
• a self-contained HTML report with options, costs, caveats, acceptance tests, and rollback conditions.

It is not a Rust rejection generator. It is equally willing to say “migrate the unsafe parser,” “extract the hot kernel,” “adopt the existing Rust library,” or “the time is in SQL; keep the application where it is.”

See it decide: twenty real projects, twenty verdicts — ten desktop applications whose teams bet on a Rust rewrite (Zed, fish, Ghostty, remacs, xi-editor, Lapce, Spacedrive, Signal Desktop, Bitwarden, KeePassXC), and ten systems and tooling projects (curl, SQLite, OpenSSL, FFmpeg, Redis, esbuild, flake8, prisma-engines, uutils/coreutils, Bun).

Install with skills.sh

The current skills CLI requires Node.js 22.20 or newer. Inspect the package first, then install it globally for your agent:

# See what will be installed
npx --yes skills@latest add xiaotonng/why-not-rust --list

# Interactive global install
npx --yes skills@latest add xiaotonng/why-not-rust \
  --skill why-not-rust -g

Non-interactive installs:

# Claude Code
npx --yes skills@latest add xiaotonng/why-not-rust \
  --skill why-not-rust -g -a claude-code -y

# Codex
npx --yes skills@latest add xiaotonng/why-not-rust \
  --skill why-not-rust -g -a codex -y

The explicit @latest is intentional: older skills CLI versions could discover a root skill but omit its bundled references/assets. This repository uses the standard skills/why-not-rust/ layout and the current CLI installs the complete package.

Try it

Natural language works across agents:

Should we rewrite this repository in Rust? Inspect the codebase and recommend the
smallest justified option, with evidence and a report.

Or invoke it explicitly:

/why-not-rust                                  # Claude Code
$why-not-rust                                  # Codex
$why-not-rust quick                            # five-question fast screen
$why-not-rust focus on packages/diff-engine    # one target only
$why-not-rust deep; our p99 target is 40 ms     # may run existing benchmarks
$why-not-rust review docs/rust-migration-rfc.md

By default, the only write is a newly named HTML report in the analyzed repository. If why-not-rust-report.html already exists, the skill uses a timestamped filename; it never overwrites a tracked or existing file without explicit permission. Builds, tests, benchmarks, and network calls are not run unless deep analysis is requested or explicitly allowed.

How it decides

The method separates four questions that a single weighted score cannot safely mix:

1. Requirement — is a measurable performance, cost, safety, correctness, or deployment gap actually real?
2. Rust-specific causality — what does Rust change after separating redesign, algorithm, database, cache, and baseline effects?
3. Economics — does the benefit beat the funded current-stack, adoption, and smaller-extraction alternatives?
4. Delivery — are compatibility, dual-run, ownership, acceptance, and rollback credible for this scope?

Twelve lenses make sure the evidence scan is complete: bottleneck ownership, Amdahl reach, tail behavior, fleet footprint, startup, safety/correctness, concurrency, distribution, ecosystem, boundary quality, delivery economics, and the strongest counterfactual.

The lenses are an evidence ledger—not additive points. Every claim names the option(s) it applies to and keeps N/A, UNKNOWN, NEUTRAL, SUPPORTS, and DISFAVORS distinct. If a decisive gate is unknown, the answer is DEFER–MEASURE + STAY for now, with the exact profile, benchmark, or cost input that can reopen the decision.

Positive and negative receipts

The 52-case library contains 24 adoptions/migrations, 7 extractions/hybrids, 12 stay-stack successes, and 9 reversals/refusals/failures. The same case often supports one goal and rejects another:

Every public number above links to the source and keeps its workload caveat. The full library includes source-check labels and explicit transfer limits; precedents are qualitative unless workload, scope, baseline, and measurement regime all match.

The report

The report is a single dark/light HTML file with:

• the decision and all four proof gates visible in the hero;
• side-by-side options with benefit, one-time/recurring cost, time-to-value, compatibility, evidence, and reversibility;
• the 12-lens claim ledger and a machine-readable assessment record embedded in the file;
• correct Amdahl and boundary math from a tested deterministic calculator;
• matched precedents with both match and mismatch fields;
• a symmetric challenge audit for migration bias and status-quo bias;
• a reversible path whose thresholds come from the actual SLO/economic break-even.

Open the full sample report.

Twenty real projects, twenty decisions

The case gallery runs twenty well-known repositories through the same four gates. Static read-only analysis at a named commit; no build, test, benchmark, or network call was run against any target. Each report ships English and 中文 in one file, with light and dark themes.

Desktop applications

Apps — mostly Mac apps — whose teams believed a Rust rewrite was the answer. Six of the ten already bet on Rust: two are dead, two have stalled, two are thriving.

Systems and developer tooling

Across the twenty: eight APPROVE, eleven REJECT, one DEFER–MEASURE, and all four scope words. Each report carries its own evidence gaps, and several decline to give a clean answer where the decisive measurement does not exist. Two of the approvals qualify themselves — Zed's says the frame rate came from leaving the web view rather than from Rust, and fish's bills the project for the RFC goal that justified the port and still has not shipped.

Repository map

• Skill instructions
• Evidence framework and proof gates
• 52-case source library
• Report style contract
• Case gallery — desktop applications
• Case gallery — systems and developer tooling
• Case sources and renderer
• Machine-readable assessment schema
• HTML report template
• Decision math calculator
• HTML and JSON safety helpers

Security model

Assessing a repository means reading text other people wrote, so the skill treats all of it — files, comments, commit messages, filenames, metadata, RFC prose, and user-supplied team/budget/compliance facts — as data under an explicit untrusted content boundary:

• instruction-like text found while scanning is quoted as evidence, never obeyed, and is surfaced in the report when it tries to steer the assessment;
• ingested content cannot change the verdict, the proof gates, the output path, or the guardrails, and cannot trigger commands, builds, installs, or network calls;
• the target repository stays read-only apart from the report at its agreed path, and the run makes no network calls unless you ask for deep;
• URLs are rendered through safe_href, never fetched, and every visible value is escaped by report_safety.py, so scanned content cannot become executable markup in the HTML report.

Limits

This is a structured decision protocol, not a statistically trained predictor. It does not estimate a universal probability that a Rust migration will succeed. Its value is traceability: every conclusion is attached to a requirement, option, claim, source, caveat, acceptance threshold, and rollback condition.

License

MIT