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.
"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.
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 reserves for the strongest available model. If a claim needs rechecking, run research-topic again instead of starting a scan here.
Steps
- Read the whole topic at
research/<topic-slug>.mdon 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.
- 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.
- 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-sourceadmits the source. Never reword an unvetted claim to hide where it came from. - References: A named crate's own documentation, changelog, 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).
- Citable roster IDs: You can promote these claims. Add the IDs to the target's
- 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 inREADME.md, in the same commit, or CI fails the pull request. - 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 applies: write the researched view into the sourced text as usual, and leave the house block beside it unchanged.
- Recompile every code example you move over on the opinion's
targets, withCARGO_BUILD_WARNINGS=deny cargo checkandCARGO_BUILD_WARNINGS=deny cargo clippy. Compile a fragment inside the smallest complete example that hosts it. Recheck each recommended crate for advisories at the version the opinion names. The toolchain and crates might have moved since the topic was written. Record the new dates, and if an advisory is open, say so in the opinion.
- Apply the change to
templates/wherever the opinion changes scaffolding, such as a[workspace.lints]entry, aclippy.tomlordeny.tomlsetting, or a crate pin.audit-freshnessreports an opinion whose template leaves out a setting it names, so land both together. Add the source IDs to the template's comment header. - 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.
- 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:. Updatelast-reviewedonly after you verify the content, as Rules describes. - Delete the research topic file, and only that file.
research/.gitkeepkeeps the directory after the last topic goes. Commit on the branchresolve/<topic-slug>, and open a pull request titleddocs: promote <topic>orresearch: discard <topic>. Fill in theopinion.mdtemplate, as 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-freshnessreports a topic that remains. Git history keeps the record. - Promotion uses
docs:, and discard usesresearch:. A promotion edits opinions, like any other opinion change. A discard touches only the staging area. Neither uses theresearch: <topic>form thatresearch-topicuses to save a topic. last-reviewedmeans 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 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-freshnesstolerance, or a new edition, or more than two stable Rust releases, shipped since. Verify its claims against their sources again, and check whetherrefresh-rust-versionsshould 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-sourceon the strongest candidate source and return to it, or discard the topic. - It covers a nightly-only feature: The freshness policy allows only a marked "Coming next" note. Promote that note if it's useful. Otherwise, leave the topic open until the feature reaches stable.
- 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-sourceschange already covered it: Discard the topic, and say so in the pull request. Duplicated guidance is worse than none.