Rust Code Quality Checks

When to Use

• After completing significant code changes
• Before creating commits
• Before creating pull requests
• When user says "check code quality", "run quality checks", "make sure code is good", etc.

Quick Approach (Recommended)

Run the comprehensive check script which handles everything automatically:

./check.fish --full

This runs all checks in order: typecheck → build → clippy → tests → doctests → docs

Benefits of using

check.fish --full

• ICE recovery: Automatically cleans cache and retries on Internal Compiler Errors
• Toolchain escalation: If ICE persists, escalates to

  rust-toolchain-update.fish

  to find a stable nightly
• Config change detection: Auto-cleans stale artifacts when Cargo.toml or toolchain changes
• Performance optimized: Uses tmpfs, ionice, and parallel jobs for speed

Other check.fish Commands

For granular control, use individual commands:

./check.fish --check

cargo check

./check.fish --build

cargo build

./check.fish --clippy

cargo clippy --all-targets

./check.fish --test

cargo test

./check.fish --doc

cargo doc --no-deps

./check.fish --full

Step-by-Step Approach (Alternative)

If you need more control or want to run checks manually:

1. Fast Typecheck

./check.fish --check
# or: cargo check

Quickly verifies the code compiles without generating artifacts.

2. Compile Production Code

./check.fish --build
# or: cargo build

Ensures production code builds successfully.

3. Format Rustdoc Comments

Invoke the

write-documentation

cargo rustdoc-fmt

This formats markdown tables and converts inline links to reference-style.

4. Generate Documentation

./check.fish --doc
# or: cargo doc --no-deps

Verify there are no documentation build warnings or errors.

If there are link warnings, invoke the

fix-intradoc-links

CRITICAL: Never remove intra-doc links to fix warnings. When you encounter:

• Unresolved link to a symbol → Fix the path using

  crate::

  prefix (see

  write-documentation

  skill)
• Unresolved link to a test module → Add

  #[cfg(any(test, doc))]

  visibility (see

  organize-modules

  skill)
• Unresolved link to a platform-specific module → Use

  #[cfg(all(any(test, doc), target_os = "..."))]

Links provide refactoring safety -

cargo doc

5. Linting

./check.fish --clippy
# or invoke the `run-clippy` skill

Runs clippy and enforces code style standards.

6. Run All Tests

./check.fish --test
# or: cargo test --all-targets && cargo test --doc

Runs all tests (unit, integration, doctests).

If tests fail, use the Task tool with

subagent_type='test-runner'

7. Cross-Platform Verification (Optional)

For code with platform-specific

#[cfg]

cargo rustc -p <crate_name> --target x86_64-pc-windows-gnu -- --emit=metadata

This checks that

#[cfg(unix)]

#[cfg(not(unix))]

When to run:

• After adding or modifying

  #[cfg(unix)]

  or

  #[cfg(target_os = "...")]

  attributes
• When working on platform-abstraction code
• Before committing changes to

  DirectToAnsi

  input handling or other Unix-specific code

ICE Recovery and Toolchain Escalation

The

./check.fish --full

ICE detected → cleanup target/ → retry
                                   ↓
                            still ICE?
                                   ↓
              escalate to rust-toolchain-update.fish
              (searches 46 nightly candidates, validates each)
                                   ↓
                         new stable nightly installed
                                   ↓
                               retry checks

This is especially important since we use nightly Rust (for the parallel compiler frontend). Nightly toolchains occasionally have ICE bugs, and this automatic escalation finds a working version.

Reporting Results

After running all checks, report results concisely to the user:

• ✅ All checks passed → "All quality checks passed! Ready to commit."
• ⚠️ Some checks failed → Summarize which steps failed and what needs fixing
• 🔧 Auto-fixed issues → Report what was automatically fixed

Optional Performance Analysis

For performance-critical code changes, consider also running:

• cargo bench

  - Benchmarks (mark tests with

  #[bench]

  )

• cargo flamegraph

  - Profiling (requires flamegraph crate)
• Invoke the

  analyze-performance

  skill for flamegraph-based regression detection

Supporting Files in This Skill

This skill includes additional reference material:

• reference.md

  - Comprehensive guide to all cargo commands used in the quality checklist. Includes detailed explanations of what each command does, when to use it, common flags, and build optimizations (wild linker, parallel frontend, tmpfs). Read this when:
  • You need to understand what a specific cargo command does
  • Troubleshooting build issues
  • Want to know about build optimizations in

    .cargo/config.toml

  • Understanding the difference between

    cargo test --all-targets

    and

    cargo test --doc

Related Skills

• write-documentation

  - For rustdoc formatting (step 3)

• fix-intradoc-links

  - For fixing doc link warnings (step 4)

• run-clippy

  - For linting and code style (step 5)

• analyze-performance

  - For optional performance checks

• test-runner

  agent - For fixing test failures (step 6)

Related Commands

• /check

  - Explicitly invokes this skill