--- name: resolve-research description: Resolve a saved research topic in research/ by weaving its recommendation into the opinion and template files or discarding it, then deleting the file once fully resolved. Use when a research topic is ready to become the opinion, when audit-freshness reports one open past tolerance, or when deciding that it has served its purpose and owes nothing further. license: See repository LICENSE compatibility: Requires git; internet access only needed to re-verify a stale research topic's claims metadata: repo: awesome-humans/dotnet change-flow: branch-pr --- **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. # Resolve a research topic `research/` is a staging area, and this skill is how a topic leaves it. A topic is evidence gathered at one point in time, and it leaves in one of two ways. Promotion weaves its recommendation into the opinions and templates, where it becomes the repository's position. Discard is just as valid: the topic answered its question, and that was its job. Either way, the file is deleted. The one exception is a partial promotion, which keeps the blocked part on disk with a note on what it's waiting for. For details, see [Edge cases](#edge-cases). ## Orchestration This is **editor-only work, so don't fan it out**. The sources were scanned when the topic was researched. What's left is deciding what an opinion says, which [agents/orchestration.md](https://raw.githubusercontent.com/awesome-humans/dotnet/main/agents/orchestration.md) reserves for the strongest available model. If a claim needs rechecking, run `research-topic` again instead of starting a scan here. ## Steps 1. **Read the whole topic** at `research/.md` on the default branch. - The research pull request must have merged, so the topic is reviewed and on record. If it's still open, merge it first. - Resolve on a new branch and pull request, never on the research branch. - The topic's closing section is the promotion plan. It names the target files, and usually the sections. Verify it before you follow it. 2. **Decide whether to promote or discard.** Ask only if the topic doesn't settle it. **Discard is a normal outcome.** A topic that found "the repository already answers this" confirmed the opinions are complete. 3. **Check every claim behind the recommendation against the roster:** - **Citable roster IDs:** You can promote these claims. Add the IDs to the target's `sources:`. - **Watch-list, unvetted, or non-roster sources:** You can't promote these claims as written. Drop the claim, back it with a roster source, or hold it until `vet-source` admits the source. **Never reword an unvetted claim to hide where it came from.** - **References:** A named package's own documentation, release notes, issues, and pull requests, or the standard behind a named format. They promote as inline links. A reference supports a reference fact without a roster source, and corroborates a roster-sourced claim. References never go in `sources:`, never support a choice or a judgement alone, and don't belong on the roster ([awesome-humans/website: Admission criteria](https://awesome-humans.net/raw/none/conventions/admission-criteria.md.txt#reserved-ids-markings-and-references)). 4. **Choose where it goes before you edit:** an existing opinion file, or a new one. Keep one topic per file, under about 300 lines, and split a file before it grows past that. A new file under `opinions/` needs a Scope bullet and a Repository layout entry in `README.md`, in the same commit, or CI fails the pull request. 5. **Write it in.** Put the opinion first, the rationale after, and the sources last. Cut the survey and hedging. Give one recommendation, and an alternative at most one line on the cost that rules it out. - Never remove, weaken, or unmark a house block or region. - If the research contradicts a house opinion, [awesome-humans/website: House opinions](https://awesome-humans.net/raw/none/conventions/house-opinions.md.txt#how-this-works) applies: write the researched view into the sourced text as usual, and leave the house block beside it unchanged. - Recompile every code sample you move over against the opinion's `targets`, and recheck each recommended package for advisories at the version the opinion names, because the SDK and packages might have moved since the topic was written. Record the new dates, and if an advisory is open, say so in the opinion. 6. **Apply the change to `templates/`** wherever the opinion changes scaffolding, such as a build property, an `.editorconfig` rule, or a package pin. `audit-freshness` reports an opinion whose template leaves out a setting it names, so land both together. Add the source IDs to the template's comment header. 7. **Fix what the research found along the way,** such as a stale example, a colliding path, or a rule enforced with no opinion behind it, in the same pull request. 8. **Update the metadata** on every file you change: an opinion's frontmatter, or a template's first-line header. Add the promoted source IDs to `sources:`. Update `last-reviewed` only after you verify the content, as [Rules](#rules) describes. 9. **Delete the research topic file,** and only that file. `research/.gitkeep` keeps the directory after the last topic goes. Commit on the branch `resolve/`, and open a pull request titled `docs: promote ` or `research: discard `. Fill in the [`opinion.md`](https://github.com/awesome-humans/.github/blob/main/PULL_REQUEST_TEMPLATE/opinion.md) template, as [agents/maintaining.md](https://raw.githubusercontent.com/awesome-humans/dotnet/main/agents/maintaining.md) describes. Its **Skill run** section names the topic, the outcome, and the roster ID behind each claim, or why the claim was dropped or held. A discard says "Doesn't apply" under the proposed opinion. ## Rules - **Only roster-sourced claims and reference facts are promoted.** This gate lets research cite anyone while opinions cite only the roster and its references. - **Promotion deletes the topic in the same pull request.** A promoted topic left on disk is a second, unapproved copy of the opinion, and the deletion is what marks it promoted. `audit-freshness` reports a topic that remains. Git history keeps the record. - **Promotion uses `docs:`, and discard uses `research:`.** A promotion edits opinions, like any other opinion change. A discard touches only the staging area. Neither uses the `research: ` form that `research-topic` uses to save a topic. - **`last-reviewed` means verified against the sources.** If the research is within the freshness tolerance, its verification holds, and today's UTC date is accurate. If not, verify it again first, as [Edge cases](#edge-cases) describes. Dating stale research records a verification that never happened. - **Rewrite the topic; don't paste it.** A topic surveys and weighs. An opinion has to be applied mechanically. ## Edge cases - **The topic is stale:** It's past the `audit-freshness` tolerance, or a major .NET release shipped since. Verify its claims against their sources again, and check whether `refresh-dotnet-versions` should run first. - **Only part of it can be promoted:** Promote the roster-sourced part and any reference fact, and cut the file down to the blocked part, with a note on what was promoted and what the rest is waiting for. Don't let one unvetted paragraph block a sound recommendation, and don't delete the blocked part without saying so. - **Everything in it is unvetted:** It can't be promoted. Run `vet-source` on the strongest candidate source and return to it, or discard the topic. - **It covers a preview feature:** The freshness policy allows only a marked "Coming next" note. Promote that note if it's useful. Otherwise, leave the topic open until GA. - **Two topics overlap,** in one opinion file or one idea: Promote them in one pull request, or in an order that doesn't rewrite the same metadata twice. - **A `harvest-sources` change already covered it:** Discard the topic, and say so in the pull request. Duplicated guidance is worse than none.