--- name: audit-freshness description: Report every resource in this repository whose last-reviewed date has drifted past tolerance, whose targets lag the latest released .NET/C#/F# versions, whose template version pins (global.json SDK band, Directory.Packages.props package versions) lag the latest stable releases, or whose sources are no longer on the AWESOME-HUMANS.md roster. Use on a periodic cadence or when asked whether the repository is stale, current, or due for a refresh. license: See repository LICENSE compatibility: Requires git; internet access only needed to check latest release versions metadata: repo: awesome-humans/dotnet change-flow: report-only --- **Reading this without a checkout?** "This repository" in this skill means [`awesome-humans/dotnet`](https://github.com/awesome-humans/dotnet). A path such as `opinions/` or `templates/Directory.Build.props` is relative to its root. Read an opinion, template, skill, or the roster from its raw copy at `https://awesome-humans.net/dotnet/raw/none/`, with `.txt` added to a Markdown file's name and a template's leading dot dropped. For a house profile, follow the links in its `llms-.txt` instead. Any other file is at `https://raw.githubusercontent.com/awesome-humans/dotnet/main/`. A skill that changes the repository needs a checkout. # Audit freshness 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](#sdk-pins) | | `` 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 ` 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](#research) | | `sources:` IDs | For the rules, see [Sources](#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](#inbound-links) | | References cited in `opinions/` and `templates/` | Zero. For details, see [Cited references](#cited-references) | | `templates/` still implement what `opinions/` require | Zero. For details, see [Templates](#templates) | | `templates/` build, test, and pass `dotnet format` without errors | Zero. For details, see [Templates](#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:` ID. - A `house:` 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](https://awesome-humans.net/dotnet/raw/none/AWESOME-HUMANS.md.txt#named-references), linked inline. It supports a reference fact alone, and corroborates a roster-sourced claim. The [admission criteria](https://awesome-humans.net/raw/none/conventions/admission-criteria.md.txt#reserved-ids-markings-and-references) 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. ### Inbound links 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](https://awesome-humans.net/dotnet/raw/none/opinions/ci.md.txt) 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](#inbound-links) describes. List every reference the opinions and templates cite, and check each, as [Cited references](#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](https://awesome-humans.net/raw/none/conventions/writing-style.md.txt#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:` 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.