Rust Stable Toolchain Assessment

Rust Stable Toolchain Assessment

Analyze a Rust crate to determine if it can be compiled with the stable toolchain. When the crate requires nightly, identify all nightly features used (directly and transitively), evaluate their stabilization status, and assess the feasibility of removing each one. Produce a structured report with confidence-rated conclusions, audited by an independent subagent before delivery.

Scope: assessment and reporting only — never modify the crate's code or create PRs.

Crate Coordinate Resolution

The user provides crate "coordinates" in one of these forms:

Form	Example	Resolution
GitHub repo + crate name	github.com/foo/bar, crate baz	Clone/navigate to the repo, locate baz/Cargo.toml
Local path	/home/user/my-crate	Navigate directly
crates.io name	serde_json	Look up the repository URL from crate metadata, then proceed as GitHub repo

If coordinates are ambiguous (e.g., a workspace with multiple crates and no crate name specified), ask the user to clarify which crate to assess.

Analysis Workflow

Phase 1: Initial Scan

1. Read Cargo.toml and rust-toolchain.toml (or rust-toolchain) to determine the declared toolchain channel and minimum Rust version.
2. Search for #![feature(...)] declarations across all .rs source files in the crate.
3. Check .cargo/config.toml for nightly-only flags (e.g., -Z flags, build-std).
4. Examine direct dependency crates for their own #![feature(...)] usage — inspect their source in the local vendor/ directory, the Cargo registry cache (~/.cargo/registry/src/), or by cloning the dependency's repository.
5. Compile a deduplicated list of every nightly feature required, noting whether it originates from the crate itself or from a dependency.

If no nightly features and no nightly-only configuration are found, the crate likely compiles on stable. Verify by attempting cargo +stable check if the toolchain is available, then produce a short positive report.

Phase 2: Feature-by-Feature Evaluation

For each nightly feature identified, evaluate these dimensions:

1. Stabilization Status

Determine where the feature sits in the Rust stabilization pipeline:

• Search for the tracking issue on rust-lang/rust using web search or gh CLI.
• Check for recent activity: merged PRs, FCP (Final Comment Period), or stabilization PRs.
• Classify the status:
  • Imminent: in FCP or stabilization PR open — likely stable within 1-2 releases.
  • Active: regular commits and discussion in the last 3 months.
  • Stalled: no meaningful progress in 6+ months.
  • Experimental: explicitly marked as incomplete or subject to redesign.

Fallback when web search is unavailable: Note the feature name and its expected tracking issue format (rust-lang/rust#NNNNN). Check the feature gate declaration in the Rust compiler source (compiler/rustc_feature/src/unstable.rs) for the issue number. Mark the status as "needs manual verification" and include the issue URL for the user to check.

2. Necessity Classification

• Performance-critical: provides functionality with no stable equivalent (e.g., unstable core/std APIs, compiler intrinsics, custom allocator APIs).
• Syntactic sugar: provides convenience but has stable workarounds (e.g., let_chains, box_patterns, nightly-only derives with manual alternatives).

Justify the classification with a concrete explanation of what the stable alternative would look like, or why none exists.

3. Removal Feasibility

• What code changes would be required to drop this feature?
• Does a stable alternative or polyfill crate exist?
• Would the change be a reasonable upstream PR (small diff, no API breakage)?
• If the feature comes from a dependency, can the dependency be patched, replaced, or pinned to an older version that does not require it?

4. Effort Estimate

Assign one of:

• Simple — minor, localized code changes; clear stable alternative exists.
• Hard but feasible — significant refactoring or dependency work, but achievable with reasonable effort.
• Blocker — no stable alternative; fundamental dependency on the feature; migration is not practical without upstream Rust changes.

Phase 3: Report Generation

Generate the assessment report following the template in references/report-template.md.

Output path: default to reports/<crate-name>-stable-assessment.md. Ask the user if they prefer a different location. Create the reports/ directory if it does not exist. If a report already exists at the target path, ask the user whether to overwrite it or append a timestamp to the new filename (e.g., <crate-name>-stable-assessment-20260316.md).

Phase 4: Independent Audit

Before delivering the report, spawn an auditor subagent to review it with a clean context.

Critical requirements for the subagent:

• Use the Agent tool to spawn a general-purpose subagent.
• Build the prompt by reading references/audit-prompt.md and substituting the full report content into the <REPORT_CONTENT> placeholder.
• The subagent must receive all context it needs in the prompt itself — it must not rely on any state or findings from the current conversation.
• The subagent returns confidence-rated conclusions.

After receiving the audit results, update the report:

• Add a confidence percentage to each conclusion in the breakdown and summary sections.
• Annotate each confidence value:
  • > 90% — GOOD
  • 70%-90% — REASONABLE
  • < 70% — POOR
• If the auditor flagged any claim as unsupported, either strengthen the evidence or explicitly note the limitation in the report.

Save the final version of the report.

Important Guidelines

• Ask, don't guess: if any information is unclear or ambiguous, ask the user before proceeding. This includes crate coordinates, scope of analysis, or unclear feature usage.
• Be skeptical: question every conclusion. Consider alternative interpretations. Think about each assessment more than once before committing to it.
• Check dependencies deeply: a crate may itself avoid nightly, but a transitive dependency might require it. Trace the full dependency tree.
• Distinguish crate vs. dependency features: the report must clearly attribute each nightly feature to its origin (the crate itself or a specific dependency).
• Scope boundary: assess feasibility only. Never modify the crate source, create branches, or open PRs.

Additional Resources

Reference Files

• references/report-template.md — Complete report structure with all required sections, formatting guidelines, and the summary table format.
• references/audit-prompt.md — Self-contained prompt template for the auditor subagent. Includes all instructions the auditor needs; substitute report content into the <REPORT_CONTENT> placeholder before use.