Skip to content

Audit freshness

View on GitHub · Raw

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

Tolerances

Check Tolerance
last-reviewed on any opinions/ file 180 days
last-reviewed after a new major .NET release ships 60 days from the release
targets: against the latest released .NET, C#, and F# Zero: any lag is a finding
last-reviewed on any commented templates/ header 180 days
sdk.version in global.json and templates/global.json Checked for shape, not band lag. For details, see SDK pins
<PackageVersion> pins in templates/Directory.Packages.props against nuget.org One minor version, or any major version. Patch-only drift is informational
The Versions verified against nuget.org … 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 dotnet format 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

SDK pins

The SDK pin is a minimum, and latestFeature picks up newer bands without an edit (refresh-dotnet-versions, step 4a). Don't report how far the pin trails the latest band. Report these instead:

  • A patch-level pin where a band minimum belongs, such as 11.0.105 instead of 11.0.100.
  • A rollForward that's missing or narrower than latestFeature.
  • A minimum whose major and minor version don't match targets:.

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.**. scripts/validate-sources.cs 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. scripts/validate-sources.cs doesn't check research/, so report an opted-out ID there.

Cited references

A reference is a named package'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 has changed state. The opinion calls it open, or relies on it as a current limitation, and it has closed, merged, or shipped in a release. Send it to harvest-sources to update or drop the note.
  • 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 skills repository, needs vet-source. A repository behind a roster source, such as dotnet/docs for ms-learn, 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, 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 property, package, 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 the format check. Run just build-templates, which assembles the example projects into the layout example.slnx describes, and runs dotnet build, dotnet test, and dotnet format --verify-no-changes. The Templates workflow runs it on every pull request and weekly, so read its latest result on main first. Analyzer and package compatibility failures show up only this way. Run the format check too: opinions/ci.md prescribes it as a CI step, and it reports style rules that the build lets through at suggestion severity, such as IDE0008. dotnet format skips F# projects and says so; that line isn't a failure.

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 .NET, C#, and F#, from the same sources as refresh-dotnet-versions step 1. Find the latest stable version of every package in templates/Directory.Packages.props, with the lookup in refresh-dotnet-versions step 4b.
    • Skip SDK band lookups: the global.json check reads the pin's shape, not its distance from the newest release.
    • 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 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-dotnet-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. scripts/validate-sources.cs 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.
  • JSON files, which have no comment syntax: The repository-root global.json, plus exactly two templates/ files: templates/global.json and templates/example.slnf. Missing metadata isn't a finding for them. Audit the pinned value against the latest release instead.
    • .slnx is XML and takes a comment header, so it isn't exempt.
    • scripts/validate-metadata.cs enforces this two-file list in CI, so any other headerless JSON under templates/ fails there.
  • A package 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.