Skip to content

Weave a house opinion

View on GitHub ยท Raw

House opinions are a house profile's preferences, such as the maintainer's simon-mckenna. They're always marked, and they sit beside the sourced text, never in it, so nobody mistakes them for community best practice. A reader or agent sees them only after choosing the profile.

"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.

Steps

  1. Take the entry from the HOUSE-OPINIONS.md inbox, with its profile. If a profile's owner asks directly, add the entry to the inbox first, so the record starts there. The profile must be in HOUSE-OPINIONS.md's Profiles table and registered for this ecosystem in awesome-humans/website: houses.toml. If it isn't, stop and ask the maintainer: a new profile needs their approval.
  2. Find where it belongs: the matching opinions/ file, and the matching templates/ file if the opinion changes scaffolding, such as a [workspace.lints] entry or a rustfmt.toml setting. If no opinion file covers it, create one under the usual rules, including its README.md Scope bullet and Repository layout entry, which CI enforces.
  3. Write it in, marked, as awesome-humans/website: House opinions defines:
    • In opinions/: A block right after the sourced recommendation it changes, outside any list. It opens with /// house | <profile> and closes with ///, each on its own line with a blank line inside. Inside, the opinion comes first, starting with House: in bold, and the rationale follows. Add house:<profile> to the file's sources:.
    • In templates/: Make the change between house:<profile> begin and house:<profile> end comment lines, in the file's comment syntax: # in TOML and // in Rust. Add house:<profile> to the sources: list in the comment header. Put a **House:** comment inside the region on the changed setting. The template must still build with the region removed.
    • Never under a heading of its own. A section that holds only a house block is empty for every other reader. Put the block in the nearest section with sourced text.
  4. Leave the sourced text whole. When the house opinion conflicts with it, the block says so and gives the reason. A reader with the profile follows the block, and every other reader the sourced text, so never cut or reword the sourced text to fit.
  5. Move the inbox entry to the Woven table in HOUSE-OPINIONS.md, with the date, the profile, and a link to where it went. Run just validate-sources, which checks that each house:<profile> ID and its blocks or regions appear together.
  6. Update last-reviewed on every file you change. Work on a house/<slug> branch, as agents/worktrees.md describes, and open a pull request to the default branch with a title that shows the house origin, such as docs: weave house opinion on <title>. Fill in the house-opinion.md template, as agents/maintaining.md describes.

Rules

  • Never present a house opinion as sourced. If a vetted source later publishes the same guidance, a harvest can add the citation inside the block, and the marking stays. Moving the guidance into the sourced text is a separate, sourced change.
  • House opinions need no source, but they need the same quality. Code must pass CARGO_BUILD_WARNINGS=deny cargo check and CARGO_BUILD_WARNINGS=deny cargo clippy on the declared targets, and the opinion must give one recommendation.
  • Only a profile owner's opinions are written in directly. Contributors propose opinions in a pull request, as the organisation's opinion pull request template describes. Once a profile's owner accepts one, it becomes a house opinion in their profile, and the Woven table's Provenance column credits the contributor and the pull request.
  • Harvest and refresh skills never remove or weaken a house block. They update the sourced text around it.

Edge cases

  • A profile's owner reverses a house opinion: Write in the reversal the same way, and mark the old Woven row as superseded. The record is append-only.
  • A house opinion becomes obsolete, for example because the compiler or Clippy now does it by default: Mark it as superseded inside its block, name the release that made it obsolete, and cite the source.
  • Two profiles change the same sourced text: Give each its own block, one after the other, sorted by profile.