akollegger/rfc-review

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

1. Read the RFC in proposals/rfc/.
2. Read proposals/rfc/README.md to confirm structural compliance.
3. Evaluate the RFC against each criterion below.
4. 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.
5. 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