Skip to content

Audit freshness

View on GitHub · Raw

Report what's stale. This skill never edits content. Version drift goes to refresh-rust-versions, and content drift goes to harvest-sources.

"This repository" in this skill means awesome-humans/rust. Run the skill in a checkout, where each path in it, such as opinions/ or templates/Cargo.toml, is relative to the repository's root.

Tolerances

Check Tolerance
last-reviewed on any opinions/ file 180 days
last-reviewed after a new edition ships 60 days from the release
targets: against the latest stable Rust release Two stable releases, which is 12 weeks. For details, see Version lag
targets: against the latest edition Zero: any lag is a finding
last-reviewed on any commented templates/ header 180 days
channel in rust-toolchain.toml and rust-version in Cargo.toml Checked for shape and for agreement with targets:. For details, see Toolchain pins
Crate pins in templates/Cargo.toml against crates.io One minor version, or any major version. Patch-only drift is informational
The Versions verified against crates.io … on <date> comment in the same file 90 days, because the pins change faster than the prose
research/ topics 90 days, then reported for resolve-research. For details, see Research
sources: IDs For the rules, see Sources
Review by YYYY-MM-DD markings in every tracked file Zero past the date. Report each for drop-or-re-date triage
Inbound links to each opinions/ and templates/ file Informational, never a finding. For details, see Inbound links
References cited in opinions/ and templates/ Zero. For details, see Cited references
templates/ still implement what opinions/ require Zero. For details, see Templates
templates/ build, test, and pass Clippy and rustfmt without errors Zero. For details, see Templates
Citation and roster URLs resolve Zero: a dead link is a content finding. Read the latest Markdown workflow run, not each URL

Version lag

Rust ships a stable release every six weeks. Bumping targets: in every file each release would bury the content changes in noise, so a file can lag by up to two releases. With 1.101 the latest, rust-1.99 is fresh and rust-1.98 is a finding. A release that stabilises something an opinion covers is a finding sooner: report the opinion as soon as the release ships, whatever its lag.

Toolchain pins

The root pins lag by the same two releases as targets:. Report these too:

  • A patch-level pin in the root rust-toolchain.toml or Cargo.toml, such as 1.99.1, where the minor release belongs (refresh-rust-versions, step 4a).
  • A template pin that doesn't follow its opinion.
  • A template's channel or rust-version whose minor release doesn't match the targets: in its header.

Research

Every topic on disk is unresolved, so all of them count. A topic still on disk after promotion is a finding, because promotion ends in deletion.

Sources

  • In an opinion or template, every ID must resolve to a Citable row in AWESOME-HUMANS.md, or be a reserved house:<profile> ID.
  • A house:<profile> ID is never a finding, in any directory.
  • In an opinion or template, a watch-list ID or a **Discovery-only.** ID is a finding. So is a file whose citable sources are all marked **Corroborate.**. just validate-sources already fails the build on all three.
  • research/ topics can name unvetted sources if the text flags them, but never an opted-out one, because its author asked not to be cited at all. just validate-sources doesn't check research/, so report an opted-out ID there.

Cited references

A reference is a named crate's or tool's own material, or a repository named under AWESOME-HUMANS.md: Named references, linked inline. It supports a reference fact alone, and corroborates a roster-sourced claim. The admission criteria define a reference fact and set the rules. Report each of these as a finding:

  • A linked issue or pull request no longer matches the claim. The opinion calls a feature unstable, or relies on an issue as a current limitation, and the issue has closed, the pull request has merged, or the feature has shipped in a release. A link cited for when a feature shipped, such as a merged stabilization pull request, is current and isn't a finding. Send a feature that has shipped in a stable Rust release to refresh-rust-versions, and any other closed issue or merged pull request to harvest-sources.
  • A reference is the only support for a claim that isn't a reference fact. The sentence or bullet has no roster citation, and it's a choice, a judgement, or a fact about something other than the reference's subject. The reference is doing a source's job.
  • A reference is in sources:. References never go there.
  • A reference points into an archived repository, or anchors a line on a branch. Link where the content moved, and pin a line anchor to a commit.
  • A reference is guidance, or publishes a roster source. Advice, such as a style guide, needs vet-source. A repository behind rust-docs, such as rust-lang/reference, is cited as its published page.

To check state, read each linked issue and pull request with gh or the web. Report one you couldn't check as "not verified", never as current.

Count what refers to each opinion and template, by link or by file name, from the repository itself: skills/, AGENTS.md, agents/, HOUSE-OPINIONS.md, the other opinions, the template comments, and research/ topics. Leave out the README.md Scope bullets and layout tree, because every opinion appears there.

Report each file with no inbound links as a pruning candidate. Nothing on the web or in another project shows up here, so a file with no inbound links might still be read. Never report it as stale on that count alone.

Templates

  • Templates match the opinions. If an opinion names a lint, key, crate, or setting, and its template leaves it out, that's a finding. People copy templates/, so a gap ships the advice without the setting.
  • Templates build, test, and pass Clippy and rustfmt. Run just build-templates. Templates have no crate of their own, so cargo run in templates/ stops with "the workspace has no members". The recipe copies templates/ to target/templates/<profile>/, as the default copy and as each house profile's, and adds one member to each with cargo new --lib crates/example, which adds itself to members and inherits the edition and [workspace.lints]. Then it runs cargo build, cargo test, CARGO_BUILD_WARNINGS=deny cargo clippy --all-targets, and cargo fmt --check. The Templates workflow runs it on every pull request and weekly, so read its latest result on main first. Lint and crate compatibility failures show up only this way. The format check covers rustfmt.toml: rustfmt exits with an error on a value it can't parse, and only warns about a key it doesn't know or one that needs nightly, so the recipe fails on that warning too.

Steps

  1. Collect the metadata from every file under opinions/ and research/, and from the comment headers in templates/: targets, last-reviewed, and sources. Count the inbound links to each opinion and template, as Inbound links describes. List every reference the opinions and templates cite, and check each, as Cited references describes.
  2. Find the latest released versions of Rust and the edition, from the same sources as refresh-rust-versions step 1. Find the latest stable version of every crate in templates/Cargo.toml, with the lookup in refresh-rust-versions step 4b.
    • Read the release announcements between each file's target and the latest release, to find the stabilisations Version lag reports early.
    • If you're offline, skip the checks you can't run, and say so in the report. Report an unchecked pin as "not verified", never as fresh.
  3. Evaluate each resource against the tolerances. Missing or malformed metadata is a high-severity finding.

    Then find every Review by marking, as awesome-humans/website: Writing style: Content defines it, with git grep -nE 'Review by [0-9]{4}-[0-9]{2}-[0-9]{2}'. It searches every tracked file, so it also finds a marking in a root document, a research topic, or a configuration comment. Skip a line that only quotes or mentions a marking, because it sets no deadline of its own.

  4. Check the roster. Flag sources in AWESOME-HUMANS.md with no published writing in over a year for vet-source re-evaluation. Repository activity doesn't count, because opinions don't cite it.

  5. Write the report, most stale first:
    • For each resource: the path, the findings, the days or releases over tolerance, and the skill that fixes it.
    • Counts of fresh, stale, and malformed resources, and the oldest last-reviewed date.
  6. Recommend next actions, usually refresh-rust-versions, harvest-sources, or resolve-research for an overdue topic. Don't run them unless asked.

Edge cases

  • A repository with no opinions yet: Report that there's nothing to check. Don't pass.
  • House content, which is house:<profile> in sources: and that profile's house blocks or regions, as HOUSE-OPINIONS.md describes: The reserved ID is never an unknown-source finding, and never suggest removing it. just validate-sources fails a build where the ID and its blocks don't appear together, or **House:** sits outside a block. Review a house block's age with its file, and never count it as stale sourced text.
  • Files with no comment header: A JSON template, because JSON has no comment syntax (agents/metadata.md). None exists today. Missing metadata isn't a finding for one. Audit what it pins against the latest release instead. The root rust-toolchain.toml and Cargo.toml aren't templates, so they have no header either, and step 4a's pins are their record.
  • A crate pinned below the latest release on purpose, for a known-bad release or a tracked major migration: Report the drift as informational once a comment beside the pin gives the reason. Deliberate staleness must look different from silent staleness.
  • A resource that doesn't depend on a version, such as naming conventions: It can declare targets: [any]. Version checks skip it, and review-age checks still apply.
  • Clock skew or future dates in the metadata: Report them as malformed.