Weave a house opinion
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
- 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. - Find where it belongs: the matching
opinions/file, and the matchingtemplates/file if the opinion changes scaffolding, such as a[workspace.lints]entry or arustfmt.tomlsetting. If no opinion file covers it, create one under the usual rules, including itsREADME.mdScope bullet and Repository layout entry, which CI enforces. - 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. Addhouse:<profile>to the file'ssources:. - In
templates/: Make the change betweenhouse:<profile> beginandhouse:<profile> endcomment lines, in the file's comment syntax:#in TOML and//in Rust. Addhouse:<profile>to thesources: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.
- In
- 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.
- 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 eachhouse:<profile>ID and its blocks or regions appear together. - Update
last-reviewedon every file you change. Work on ahouse/<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 asdocs: weave house opinion on <title>. Fill in thehouse-opinion.mdtemplate, 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 checkandCARGO_BUILD_WARNINGS=deny cargo clippyon the declaredtargets, 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.