Skip to content

Vet a source

View on GitHub ยท Raw

Apply the admission criteria in AWESOME-HUMANS.md to a candidate source, or re-evaluate an existing one. Every opinion cites only the roster, so when in doubt, decline.

Orchestration

As agents/orchestration.md describes, delegate the evidence gathering in step 3, such as searching archives and sampling posts, to worker agents. Only the editor weighs the evidence, decides, and edits the roster.

Steps

  1. Identify the candidate: its URL, author, and focus area. If the roster already lists it, this is a re-evaluation for promotion or demotion, not an admission. A source in ## Opted out that asks to return is the exception: it's a suggestion like any other, so vet it as an admission.
    • From an issue: When you're given an issue number, read it with gh issue view <number> --json title,body,labels. An issue labelled vet-source came from the Suggest a source form, which awesome-humans/website's intake moved here. Its form fields give the name, the main URL, three sample posts, the year writing started, why the suggester thinks it qualifies, and their relationship to the source. Treat them as leads to check, never as evidence.
    • An opt-out: An issue labelled opt-out names a source whose author asked to stop being cited, and the maintainer verified the request. Skip to Opt-outs.
  2. Check every ecosystem's opt-outs first. An opt-out from one ecosystem covers all of them, so read the ## Opted out section of every other ecosystem's AWESOME-HUMANS.md before you gather any evidence.
    • List the ecosystem repositories with gh repo list awesome-humans, and read each roster with gh api repos/awesome-humans/<repository>/contents/AWESOME-HUMANS.md -H 'Accept: application/vnd.github.raw'. Today that's awesome-humans/rust.
    • A candidate listed there is declined without vetting. Never re-run the criteria on it: its author asked not to be cited. Add no roster row and no source notes. Skip to step 6.3, and log the decline with a link to the other roster's entry, in a pull request that holds only the log entry.
    • If this roster lists the source too, don't log a decline. Follow Opt-outs for it here, and link the other roster's entry where Opt-outs step 3 links the awesome-humans/website issue.
  3. Establish the track record against each criterion:
    • Longevity: Find the earliest verifiable publication, from archives, post history, or the Wayback Machine. Admission needs two years of sustained output, and less means the watch list, whatever the quality. Record the exact start year in the roster's Since column.
    • Depth: Sample three to five representative posts. Do they offer original insight, such as internals, measurements, or worked reasoning, or do they paraphrase release notes?
    • Accuracy: Has the source published corrections? Has it left claims standing that were later shown wrong?
    • Independence: Does the content stand on its merit, or on marketing reach? Vendor blogs and personality-driven channels need extra scrutiny.
  4. Classify the source, applying the two qualifying rules in awesome-humans/website: Admission criteria exactly as written there:

    Evidence Outcome
    All four criteria met, over two years or more Admit to the Citable table
    An independence concern that applies Admit, with a usage limit in the notes
    Publishing stopped over a year ago Watch list, unless the writing clearly continues elsewhere
    Strong on depth and accuracy, but short on longevity Watch list, with the blocker recorded
    An aggregator, such as a link roundup or newsletter Admit, marked **Discovery-only.**. It never appears in sources:
    Thin on depth, but sound on the other three criteria Admit, marked **Corroborate.**
    Anything else Decline, with a one-line reason in the pull request only

    The table decides whether a source is citable. A marking or a usage limit says what a citation can rest on.

  5. For a re-evaluation, promote a watch-list source whose blocker has cleared. Demote or annotate an admitted source that has published nothing in over a year, or whose quality has dropped.

    • A source whose quality drops gets either a tighter usage limit in its notes, or the watch list.
    • A demoted source keeps its row, with a note. Moving a source to the watch list revokes citation, back catalogue included, and scripts/validate-sources.cs rejects a watch-list ID in any sources:.
    • So a demotion is finished only when no opinion cites the source. In the same pull request, re-source each affected claim from a citable source, or drop it. To keep the back catalogue citable, annotate the row instead of demoting it.
  6. Edit in a worktree on the branch vet/<source-id>, or a slug for a multi-source pass, as agents/worktrees.md describes:
    1. Update the roster table. Assign a stable kebab-case id, set its Kind to person or publication as AWESOME-HUMANS.md: How the roster is organised defines, and insert the row in ID order. If the same source is on another awesome-humans ecosystem's roster, use its id and Kind there. If the row enters or leaves the Citable table, update all three counts in the sentence above it: the total, the people, and the publications. scripts/validate-sources.cs checks each against the rows.
    2. Add the source's section under ## Source notes, also in ID order, with the evidence and any marking, in the verdict-then-labelled-bullets shape the section's introduction describes.
    3. Add the decision to the decision log, in two sentences: the decision and the fact behind it. Put the evidence for each criterion in the pull request. For a suggestion the source made of itself, say so in the log entry.
  7. Open a pull request, filling in the source.md template, as agents/maintaining.md describes. It takes the decision, the evidence for each criterion, the decision log line, and, for a demotion, each claim re-sourced or dropped. A person approves it before the source can feed opinions.
    • From an issue: End the description with a Closes: #<number> trailer, and comment the outcome on the issue: the decision, one line per criterion, and the pull request.
    • A decline from an issue still gets a pull request, with only the decision log entry, because the form promises that the log records every outcome.

Opt-outs

An opt-out removes citations, and the roster keeps only enough to turn away a later suggestion. Finish it within 30 days of the maintainer's verification, in one pull request on the branch vet/opt-out-<source-id>:

  1. Move the row to the ## Opted out table, in ID order. If the section still reads "No source has opted out.", replace that line with a table that has the same columns as the others. If the row leaves the Citable table, update all three counts above it, as for a demotion.
  2. Delete the source's section under ## Source notes. scripts/validate-sources.cs fails while it's there.
  3. Log the decision: the date, the source ID, and the link to the awesome-humans/website issue. Never quote the requester or name anyone beyond the source ID.
  4. Re-source every citation. scripts/validate-sources.cs lists each opinion and template that still cites the ID. Re-source each claim with research-topic, or cut it back to what other citable sources support. In the pull request, list each claim and what happened to it.
  5. Open the pull request with the source.md template and a Refs: awesome-humans/website#<number> trailer, which doesn't close the issue. Comment the pull request on the awesome-humans/website issue, which the maintainer closes once every ecosystem's pull request has merged. When step 2 sent the source here and there's no issue, leave out the trailer and the comment, and link the other roster's entry in the description instead, with a reference-style link.

Opting back in is a suggestion like any other. The source leaves ## Opted out only on admission.

Edge cases

  • Institutional sources, such as Microsoft or JetBrains: Longevity belongs to the publication, not individual authors. When you cite one author, still check their depth.
  • An author who moved platforms, for example from a personal blog to an employer's engineering blog to a newsletter: The track record follows the person, so combine their writing across platforms. A move to video, talks, or a podcast leaves the scope (awesome-humans/website: Admission criteria).
  • A candidate found through one viral post: Never admit a source on one post. At most, watch-list it.
  • Conflicts of interest, where the candidate sells a product the opinions might recommend: You can admit it, but record the conflict in its ## Source notes section, so opinions that cite it flag it.