agentleFS
grafanagrafana/gcx/.agents/skills/review-rfc/SKILL.md

review-rfc

Skill836 starsChanged 19 days agoApache-2.0View on GitHub

Review an engineering RFC before it is shared or accepted. Checks its claims against code and documentation, its scope against the originating request, repository rules, internal consistency and template structure, then reports author decisions, fixes and side-channel questions. Trigger on "review this RFC", "check the RFC against <issue>", "is this RFC ready to share". Not for drafting or revising an RFC (create-rfc), reconciling one with implementation (update-rfc), or reviewing a code PR (review-pr).

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. nurettincoban/ai-prd-workflow★ 300same name
    2. dannys-code-corner/incan★ 74same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository8 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run every check. Claims, scope and repository rules are independent: bounded research agents may run them in parallel, and every citation …

    line 18

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Review RFC

Review the RFC as it stands and produce a report. The author owns the decisions; the RFC changes only when they ask, and then the writing rules in create-rfc apply. Posting the report to a PR or issue is a separate action that needs its own authorization.

Gather

Read the RFC, the RFC conventions and the template. Find the originating request (issue, notes, earlier decisions) and the code, documentation and other RFCs the RFC's claims touch. If the RFC has uncommitted or recent edits, compare it with the previous revision: content removed in the edit is part of the review.

Done when every source is read, or named in the report as unavailable. Without the originating request the scope check cannot run; ask for it or report the gap.

Checks

Run every check. Claims, scope and repository rules are independent: bounded research agents may run them in parallel, and every citation they return is verified before it enters the report.

  1. Claims. Every statement about existing behavior is a claim: gcx code and framework capabilities, product APIs, documentation, and precedents the RFC says it follows. Verify each against its primary source and cite file:line or the document section. Look hardest at framework features the design assumes, at whether a cited precedent really behaves as described, and at whether each API operation the design depends on exists and does what the design needs. Done when every claim is verified, contradicted or marked unverifiable.
  2. Scope drift. Map each requirement in the originating request to the RFC: covered, explicitly excluded, or deferred to named follow-up work. Anything else is a finding, and so is scope the RFC adds without saying why. Done when every requirement has a mapping.
  3. Repository rules. Walk the compliance hierarchy in AGENTS.md in order and name each rule the design touches, with a verdict. Report implementation-level rules, such as test gates, exit codes and output registration, only when they change the design. Done when every touched rule has a verdict.
  4. Consistency. Read each example, diagram, table and walkthrough against the rules it illustrates. Every step a rule requires appears in the walkthrough; every field and flag in an example is defined by the rules, and every rule is reflected in the examples; renamed concepts are renamed everywhere; links and anchors resolve. Done when every example and diagram has been read against its rule.
  5. Settled versus open. For each choice the RFC calls settled, check that its enabling contract is established. A settled choice resting on an open question is a finding: it needs a stated fallback or belongs among the open questions. Each open question says what would resolve it. A settled decision reopens only on new evidence, so name the evidence. Done when every settled choice and every open question has been checked.
  6. Structure. For new proposals, compare the sections with the template, in order. Historical records may retain their original structure under the RFC conventions. Each section does its job: Drawbacks names costs, Rationale and alternatives names the alternative to each consequential choice and its cost, and Prior art names the patterns reused or departed from and what each teaches. Each rule has one home, and status lives near the RFC title. Run this check last; it is the cheapest.

Side-channel questions

Some findings rest on sources the RFC cannot cite, or on detail that belongs outside it. Keep that detail out of the RFC text and out of suggested wording, and list the questions separately so the author can raise them through another channel. When a fix depends on such detail, propose wording that states only the property the design needs.

Report

Rank findings by what they cost the design, most costly first, and write each one so the author can act on it without rereading the sources:

  1. Decisions for the author: choices the review cannot make, such as scope questions and settled choices that new evidence undermines. Give a recommendation and its main tradeoff.
  2. Fixes: contradicted claims, rule violations and consistency defects. Give the RFC location, the evidence and proposed wording.
  3. Side-channel questions: the separate list described above.
  4. Structure and editorial: a few lines at most.

Close with what the review could not check and why.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.