| name | rfc-review |
| description | Review a draft RFC for scope, clarity, and contributor-readiness. Use before opening an RFC for comment or merging a proposal branch. Produces concrete suggested revisions, not just a report. |
RFC Review
Overview
Use this skill to evaluate a draft RFC against a consistent set of quality criteria before it is opened for comment. Works for self-review by the author, maintainer review during a PR, or peer feedback from a collaborator. Produces specific, actionable suggested revisions — not a checklist of observations.
Workflow
- Read the RFC in
proposals/rfc/.
- Read
proposals/rfc/README.md to confirm structural compliance.
- Evaluate the RFC against each criterion below.
- For each criterion that fails or is weak, draft a specific suggested revision — quote the problematic text and propose replacement text or a concrete addition.
- Summarize findings: what is strong, what needs revision, and what is blocking vs. advisory.
Review Criteria
1. Scope fit
Is the RFC the right size for its stated purpose?
- A PoC RFC should specify layout and boundaries, not implementation detail.
- A feature RFC should specify behavior and interfaces, not code.
- A subsystem RFC should specify contracts and failure modes, not algorithms.
Flag: RFC specifies code, method signatures, or implementation detail that belongs in the implementation, not the proposal.
Flag: RFC is so vague that an implementer would face constant ambiguity about what was agreed.
2. Acceptance criteria anchored in behavior
Can a contributor tell when the work is done by observing something, not by checking off packages created?
- Acceptance criteria should describe what a user, agent, or system does and sees.
- Package structure and file layout are not acceptance criteria.
Flag: No user stories, demo scenario, or observable acceptance criteria present.
Flag: Acceptance criteria describe structure ("the registry package exists") rather than behavior ("a ghost can register and receive a token").
3. Demo scenario
Is there a concrete path a contributor follows to verify the work?
- Should include: what to run, in what order, and what to observe.
- Should be completable by a new contributor within a stated time (e.g. 15 minutes).
Flag: No demo scenario or "getting started" path described.
Flag: Demo scenario assumes knowledge not present in the RFC or repo README.
4. Implementation readiness
Is there enough information for implementation to begin without another round of design?
- Key interfaces, tool names, or API shapes should be named (not fully specified).
- Open questions should be listed explicitly, not hidden.
- Dependencies between packages should be clear.
Flag: A contributor would need to make significant design decisions not acknowledged as open questions.
Flag: Open questions are present but not listed — they are buried in prose or implicit.
5. Over-specification
Is the RFC constraining implementation detail that should be left to the implementer?
- Method signatures, data structure internals, and algorithm choices belong in code.
- Interface names and tool names are appropriate to specify; their implementations are not.
Flag: Code blocks present that specify implementation rather than illustrate intent.
Flag: RFC would be wrong if an implementer chose a different variable name or data structure.
6. Alternatives
Are the alternatives realistic comparisons that help a reader understand why this approach was chosen?
- Each alternative should name a real option that was genuinely considered.
- Rejection reasons should be specific to this project, not generic.
Flag: Alternatives are strawmen that no contributor would actually propose.
Flag: A significant alternative is missing — one a reviewer would ask "why not X?" about.
7. Consistency with architecture
Does the RFC align with decided components and open questions in docs/architecture.md?
- It should not silently contradict decided technology choices.
- If it resolves an open question, it should say so explicitly.
- If it challenges a decided component, it should reference or propose an ADR.
Flag: RFC introduces a technology or pattern inconsistent with docs/architecture.md without explanation.
Output Format
## RFC Review: [RFC title]
### Summary
[2-3 sentences: overall assessment and whether it is ready to open for comment]
### Blocking Issues
[Issues that must be resolved before the RFC is ready. For each: criterion, problem, suggested revision.]
### Advisory Issues
[Issues worth addressing but not blocking. Same format.]
### Strengths
[What is working well and should be preserved.]
For each blocking or advisory issue, include:
- Criterion: which of the seven criteria applies
- Problem: what is wrong or missing, with a quote if relevant
- Suggestion: specific text to add, remove, or replace
