Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion skills/research-topic/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,11 @@ As [AGENTS.md: Orchestration and model economy](../../AGENTS.md#orchestration-an

5. **Write the research topic:**
- Put the recommendation or current state in the opening sentences, and the detail after.
- Cite a source ID for every claim. Note a source's standing when it limits the claim, such as `**Corroborate.**` or a limit in its notes. Date anything time-sensitive.
- Cite a source ID for every claim. Note a source's standing when it limits the claim, such as `**Corroborate.**` or a limit in its notes. Date anything time-sensitive. Mark a claim that rests only on a reference, or on your own reading, as unsupported, so `resolve-research` doesn't promote it.
- **Label nightly-only features as the freshness policy requires:** "unstable on nightly as of `<date>`, not yet an opinion". Keep them separate from stable guidance.
- Where sources disagree, say so, and weigh them. Don't blur them into a vague middle.
- **Compile every code example** on the declared `targets` before you save the topic, as [AGENTS.md: Writing style for opinions](../../AGENTS.md#writing-style-for-opinions) asks of an opinion: it passes `cargo check` and `cargo clippy -- -D warnings`. Under the example, record the toolchain, the crate versions, and the date you compiled it. For a fragment that can't compile alone, compile the smallest complete example that hosts it, and say so. CI doesn't compile research, so an example you didn't build reaches `resolve-research` unchecked.
- **Check every crate the topic recommends for security advisories** at the version it names: run `cargo deny check advisories` in a project whose `Cargo.lock` resolves the crate to that version, such as the one you compiled the examples in, or look the crate up in the [RustSec Advisory Database](https://rustsec.org/). Record the date, and say so in the topic if an advisory is open.
6. **Answer follow-up questions** from what you've gathered. Sweep again, in the same order, only when a question goes beyond it.
7. **Close the loop.** End with what the research revealed about the repository, and recommend the matching skill. Never run it unprompted.

Expand Down
1 change: 1 addition & 0 deletions skills/resolve-research/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ This is **editor-only work, so don't fan it out**. The research did the sweeping
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 why it lost.
- Never remove, weaken, or unmark a house block or region.
- If the research contradicts a house opinion, [awesome-humans/website: House opinions](https://github.com/awesome-humans/website/blob/main/pages/conventions/house-opinions.md#how-this-works) applies: write the researched view into the sourced text as usual, and leave the house block beside it unchanged.
- Recompile every code example you carry over on the opinion's `targets` with `cargo check` and `cargo clippy -- -D warnings`, compiling a fragment inside the smallest complete example that hosts it, and recheck each recommended crate for advisories at the version the opinion names, because the toolchain and crates might have moved since the topic was written. Record the new dates, and say so in the opinion if an advisory is open.
6. **Carry the change into `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](#rules) describes.
Expand Down
Loading