--- name: harvest-sources description: Scan the vetted sources in AWESOME-HUMANS.md for new posts and updates, then fold notable guidance into the opinion files. Use on a periodic cadence, or when asked to check what the awesome humans have published lately, or after a major community post (such as a Rust release announcement or a new chapter of the Rust Performance Book) ships. license: See repository LICENSE compatibility: Requires git and internet access metadata: repo: awesome-humans/rust change-flow: branch-pr --- # Harvest sources Collect what the vetted sources have published since the last scan, and update the opinions from it. "This repository" in this skill means [awesome-humans/rust](https://github.com/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 As [agents/orchestration.md](https://awesome-humans.net/rust/raw/none/agents/orchestration.md.txt) describes, fan the per-source scans in step 3, and the citation checks in step 6, out to worker agents. Only the editor triages their findings and edits `opinions/`, `templates/`, and `research/`. ## Steps 1. **Load the roster** from [AWESOME-HUMANS.md](https://awesome-humans.net/rust/raw/none/AWESOME-HUMANS.md.txt). Only sources in the **Citable** table feed opinions. Use watch-list sources for discovery and cross-checking only: what you find there needs a citable source, or a `vet-source` admission, before it can change an opinion. 2. **Set the scan window,** from the most recent harvest entry in the `AWESOME-HUMANS.md` decision log to today in UTC. If there's no harvest entry, start from the newest `last-reviewed` date in `opinions/`. 3. **Scan each source** for posts in the window. A source marked `**Discovery-only.**` only leads to primary posts: follow its links, and never cite it in `sources:`, because CI rejects it. 4. **Triage each notable post:** - **Changes an existing opinion:** It replaces or refines guidance in `opinions/`. Queue an edit. - **Suggests a new opinion:** It's a recurring theme that no opinion covers yet. First check `research/` and the open pull requests on `research/` branches. If a research topic covers the subject, add the post to that topic instead of a stub: - **A topic in `research/`:** Add the post's point to the topic, and its source ID to the topic's `sources:`, in the harvest pull request. Leave the topic's `last-reviewed:` as it is because the rest of the topic wasn't checked. - **A topic in an open research pull request:** Comment the post's link on that pull request, so the topic can include it before it merges. Never push to another skill's branch. Otherwise, create a stub opinion with metadata, the source link, and a `TODO`. In the same commit, add it to `README.md` as a Scope bullet and a Repository layout entry, or CI fails the pull request. - **Noise:** Release news, marketing, or a one-off tip that doesn't generalise. Skip it. 5. **Edit in a worktree** on the branch `harvest/`, dated the day the scan window ends, as [agents/worktrees.md](https://awesome-humans.net/rust/raw/none/agents/worktrees.md.txt) describes: - Keep one recommendation per opinion. If a post contradicts the current opinion, choose the position with the stronger sources or evidence, and note the change in one line. - **Never remove, weaken, or unmark a house block or region** ([awesome-humans/website: House opinions](https://awesome-humans.net/raw/none/conventions/house-opinions.md.txt#how-this-works)). Update the sourced text beside it as usual. When a source now agrees with a house opinion, add the citation inside its block. - Add the post's source ID to the opinion's `sources:`, and update `last-reviewed:`. - **Add a reference where it confirms a specific behaviour.** When an edit says how a named crate or tool behaves, or when a feature shipped, link its own material: its documentation, changelog, an issue, a test, or a line of source. A repository named under [AWESOME-HUMANS.md: Named references](https://awesome-humans.net/rust/raw/none/AWESOME-HUMANS.md.txt#named-references) qualifies too, such as an RFC or a stabilization pull request. Look only in the repositories that section names, not elsewhere in their organisations. Link an RFC or a RustSec advisory by the published page that section gives. The [admission criteria](https://awesome-humans.net/raw/none/conventions/admission-criteria.md.txt#reserved-ids-markings-and-references) decide what qualifies. Read a reference before you link it, and link it only if it says what the claim says. It never goes in `sources:`. A reference fact, as the admission criteria define it, needs no roster citation. For a choice or a judgement, it sits beside the roster citation and never replaces it. Pin a link to a line of code to a commit. - **Check a contradiction against the crate's own material.** When a post contradicts an opinion about how something behaves, read the crate's documentation, tests, or source before you choose. If they settle it, correct the opinion, and cite a roster source that agrees, or that material as a reference. Link the evidence in the pull request. 6. **For the claims this harvest added or changed, check their citations** with steps 2 to 4 of [`review-opinions`](https://awesome-humans.net/rust/raw/none/skills/review-opinions/SKILL.md.txt). Include each changed claim's citations even when their own lines didn't change, such as a citation on the line after the claim it supports. You extract the pairs and triage the results, and worker agents check the pages. Act on each category from its step 4 before you go on: - **Contradicted** or **Unsupported:** Fix the claim or its citation, or drop the edit. - **Drifted:** Update the quote to match the page. - **Misplaced citation:** Move the citation to a line of its own after the block it covers. - **Missing source:** Drop the claim, and propose the source with `vet-source`. Never merge it unsourced. - **Not verified:** List the page and the reason in the pull request. 7. **Record the scan** in the `AWESOME-HUMANS.md` decision log: the date, the window, and what changed, as briefly as the existing entries. Per-source findings go in the pull request, not the table. 8. **Open a pull request** to the default branch, filling in the [`opinion.md`](https://github.com/awesome-humans/.github/blob/main/PULL_REQUEST_TEMPLATE/opinion.md) template, as [agents/maintaining.md](https://awesome-humans.net/rust/raw/none/agents/maintaining.md.txt) describes. Its **Skill run** section takes the findings per source, and the proposed opinion takes the changes per opinion. A person reviews it before it changes any opinion. - If an open `Harvest due: ` issue asked for this scan, end the pull request description with a `Closes: #` trailer. - The `Harvest reminder` workflow opens that issue on the 1st of each month, and skips the month while an issue with that title is open. An issue left open blocks the next reminder. - If another pull request replaces this one, copy the `Closes:` trailer to it, because GitHub doesn't move it. ## Edge cases - **Vetted sources disagree:** Present both positions in the pull request, and choose one for the opinion, with the reason. Never leave a menu in the opinion. - **A source has stopped publishing, or its quality has dropped:** Note it in the pull request, and propose demotion through `vet-source`. Don't edit the roster directly. - **Nightly-only content:** It can go in a "Coming next" note, never in the opinion itself. - **A linked issue has closed:** If an opinion links a tracking issue or pull request as unstable or as an open limitation, and it has closed, update or drop the note in the same scan. If the feature has shipped in a stable Rust release, leave it to `refresh-rust-versions`. `audit-freshness` finds both kinds, and names the skill for each. - **Nothing notable found:** Record the scan in the decision log anyway, on the default branch or in a small pull request, so the next window starts from the right date. Close the reminder issue either way, or next month's reminder doesn't open.