Skip to content

Resolve a research topic

View on GitHub ยท Raw

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

  1. Read the whole topic at research/<topic-slug>.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 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).
  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 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, with CARGO_BUILD_WARNINGS=deny cargo check and CARGO_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.
  6. Apply the change to templates/ wherever the opinion changes scaffolding, such as a [workspace.lints] entry, a clippy.toml or deny.toml setting, or a crate 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 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/<topic-slug>, and open a pull request titled docs: promote <topic> or research: discard <topic>. Fill in the opinion.md template, 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-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: <topic> 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 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 new edition, or more than two stable Rust releases, shipped since. Verify its claims against their sources again, and check whether refresh-rust-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 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-sources change already covered it: Discard the topic, and say so in the pull request. Duplicated guidance is worse than none.