rust-hygiene-audit

name

rust-hygiene-audit

description

Run a deep DRY + code-hygiene audit of the Rust workspace and turn the findings into verified, deduplicated, hierarchical GitHub tech-debt issues. Use this whenever the user asks to find duplication, code smells, derive/boilerplate bloat, oversized files, or "tech debt"; to tighten the Clippy/lint posture; to mass-file or triage hygiene issues; or to assign Priority/Effort issue Fields across the backlog. Reach for it even when the user only says "clean up the codebase", "find DRY violations", "what should we refactor", or "make issues for the cruft" — it is the right tool for evidence-backed, non-spammy hygiene issue creation.

Rust Hygiene Audit

Turn a fuzzy "clean up the codebase" request into a set of evidence-backed, deduplicated, parent/child GitHub issues — without flooding the tracker with smells. The guiding principle: every issue must cite real file:line evidence that survived an adversarial check, and must not duplicate an open issue.

This skill is for hygiene/DRY/lint work, not behavior changes. It produces issues and field assignments; it does not edit compiler logic. Keep parity work (tsc matching) in the owner skills.

The four phases

Run them in order. Phases 1–2 are analysis; 3–4 are writes — confirm scope with the user before mass-creating issues unless they already said "create them".

1. Measure the Clippy posture (prevention evidence)

The cheapest lever against future debt is a tighter lint floor, so quantify what the current floor lets through before proposing changes.

python3 .agents/skills/rust-hygiene-audit/scripts/measure_clippy.py --worktree . --out /tmp/hygiene

This runs cargo clippy --workspace --lib -- -W clippy::pedantic -W clippy::nursery (no files touched), aggregates warnings per lint, and prints a promote vs defer triage. Read references/lint-triage.md for the rationale behind which lints are worth promoting in a compiler (numeric casts and must_use/doc pedantry are mostly intentional; idiom/ownership lints are high-signal). The count and triage become the body of the clippy-posture epic.

Disk note: a cold workspace clippy build needs ~8–12GB. If low, reclaim merged worktree caches first (see tsz-disk-cache-hygiene).

2. Fan out the audit (find + verify)

Drive the bundled workflow, which fans out per-crate DRY auditors and cross-cutting concern auditors, dedups against open issues, then adversarially verifies every candidate against the real source before authoring full issue bodies:

Workflow({ scriptPath: "scripts/agents/hygiene-audit-workflow.mjs" })

Before launching, snapshot the open issues the auditors dedup against:

gh issue list -R <owner>/<repo> --state open --limit 300 --json number,title,labels > /tmp/hygiene/open-issues.json

The workflow returns { epics, children, dropped, stats }. children carry verified evidence and full body_md. dropped records findings that overlapped an existing issue — surface these so the user sees the dedup worked. Tune the auditor list (crates + concerns) in the workflow's CRATES/CONCERNS arrays for the target repo. The verify stage defaults to reject on weak evidence — that is the anti-spam gate; do not weaken it.

3. Create the issue hierarchy

Author epic body_md (summarize the theme + bake in the measured clippy data for the lint epic), then create epics and children with native sub-issue links:

python3 .agents/skills/rust-hygiene-audit/scripts/create_issues.py \
  --repo <owner>/<repo> --specs /tmp/hygiene/result.json --apply

Match the repo's existing issue conventions. For tsz that is the techdebt(scope): title + the template in references/issue-template.md (## Summary with a structural rule → ## Evidence → ## Why it matters → ## Proposed fix (sized S/M/L) → ## Risks / coordination). The script writes a ## Child issue map into each epic as a durable fallback even when native linking succeeds.

4. Assign Priority / Effort Fields

python3 .agents/skills/rust-hygiene-audit/scripts/assign_fields.py \
  --repo <owner>/<repo> --specs /tmp/hygiene/result.json --apply

Discovers the repo's Priority/Effort single-select issue Fields by name, then assigns by rule. Default priority ranking is correctness > speed > tech-debt (map to High/Medium/Low; reserve Urgent for urgent/panic labels). Effort comes from the audit size (S/M/L → Low/Medium/High) and epic-scale → the top level. See references/github-fields-api.md for the API gotchas — they are easy to get wrong:

• Sub-issues: gh api -X POST .../issues/<parent>/sub_issues -F sub_issue_id=<db_id> — -F (integer) not -f (string); the id is the issue database id, not its number.
• setIssueFieldValue works with repo scope, but createIssueField / updateIssueField (changing a field's options) need admin:org. If you must add an option and lack the scope, ask the user to add it in the UI or fall back to the existing options.

What good output looks like

• Issues cite ≥2 real sites for any DRY claim and name the structural rule.
• Duplication that already drifted into a parity bug is flagged as such — that is the highest-value finding, not a cosmetic one.
• Nothing duplicates an open issue (the dropped list proves the check ran).
• A small number of strong epics, each with actionable PR-sized children.

What to avoid

• Smell-only issues with no file:line evidence.
• Mass-creating before the user has agreed to issue creation.
• Architecture-boundary refactors that overlap an active campaign — check open issues first and let the auditors dedup.
• Fixture-name / rendered-output string checks in any proposed fix (repo anti-hardcoding gate).