Skip to content

chore(skills): cut the rfc skill to a 1-2 pager #511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
filvecchiato merged 2 commits into from
Aug 26, 2026
+40 −172
Merged

chore(skills): cut the rfc skill to a 1-2 pager #511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dec54ad
chore(skills): cut the rfc skill to a 1-2 pager
filvecchiato Aug 26, 2026
2dec831
Merge branch 'main' into docs/agents-md
filvecchiato Aug 26, 2026
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
151 changes: 25 additions & 126 deletions .claude/skills/rfc/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,139 +1,38 @@
---
name: rfc
description: Write an RFC document based on user-provided notes and context. Use when the user wants to create, draft, or write an RFC.
description: Draft a short RFC for this repo. Use when the user wants to create, draft, or write an RFC.
argument-hint: [topic or brief description]
context: fork
---

# RFC Writer
# RFC

You are an RFC writer. Your job is to produce a high-quality, precise, and complete RFC document based on the user's notes and context. The RFC must follow the Polkadot Fellows RFC template structure (see [template.md](template.md)).
Write a 1-2 page RFC. It exists to get agreement on an approach, not to specify it:
details are the implementer's call and need no prior approval here.

## Process
## Mechanics

### Phase 1: Gather Context
- File `docs/rfcs/<kebab-title>.md` from [template.md](template.md). **Do not number it**
and **do not touch `_index.md`** — `number-rfc.yml` assigns the number on merge to
`main` and rebuilds the index from the files on disk.
- Keep the H1 as `# RFC — Title`, em dash included; the numbering step rewrites that
exact form to inject the number.
- Set `status: draft` in the frontmatter. Omitting it makes CI index the RFC as
`accepted`.
- `check-rfc.yml` fails any PR touching `docs/rfcs/**` that does not also change
`rust/crates/truapi/`. A host-side proposal cannot satisfy that and belongs in
`docs/features/` instead.

The user will provide some combination of:
- Notes describing what the RFC should cover
- An existing spec or RFC that this new RFC aims to adjust
- A PRD or design document
- Verbal explanation of the problem and proposed solution
- Code references or technical context
## Writing it

**Your first action is to read and deeply understand everything the user provides.**
- Lead with the problem. If it isn't concrete, the RFC isn't ready.
- Describe what changes and why, not signatures, thresholds or edge cases.
- Cut every sentence that would not change a reader's mind.
- Prefer a stated assumption to a blocking question. Ask the author only when the
answer changes the approach.
- Omit any section you would otherwise fill for the template's sake.

If the user passes arguments (`$ARGUMENTS`), treat them as the initial topic/notes.
## Before handing it over

### Phase 2: Clarifying Questions

**This is the most critical phase. You MUST ask clarifying questions before writing the RFC.**

Do NOT proceed to writing until you are confident that every aspect of the RFC will be concrete and specific — nothing should remain vague, ambiguous, or hand-wavy.

Ask questions in focused, numbered batches (5-8 questions max per round). Group them logically. Continue asking rounds of questions until you have full clarity.

Areas you must have clarity on before writing:

1. **Problem & Motivation**: What exact problem does this solve? Who is affected? What's the impact of not solving it? Are there concrete examples or incidents that motivate this?

2. **Proposed Solution**: What specifically is being proposed? What are the exact mechanics? How does it work step-by-step? What are the key design decisions and why were they made?

3. **Scope & Boundaries**: What is explicitly in scope? What is explicitly out of scope? Are there related problems this intentionally does NOT address?

4. **Stakeholders**: Who are the primary stakeholders? Has this been discussed with anyone? What feedback has been received?

5. **Trade-offs & Alternatives**: What alternative approaches were considered? Why were they rejected? What are the known drawbacks of the chosen approach?

6. **Technical Details**: Are there specific interfaces, data structures, algorithms, or protocols involved? What are the exact parameters, thresholds, or configurations?

7. **Compatibility & Migration**: Does this break anything existing? How do existing users/systems migrate? Is backwards compatibility maintained?

8. **Edge Cases**: What happens in failure scenarios? What are the boundary conditions? Are there race conditions or ordering concerns?

9. **Testing & Verification**: How can correctness be verified? What testing approach is appropriate?

10. **Unresolved Questions**: Are there aspects the author is genuinely unsure about and wants community input on?

**Rules for clarifying questions:**
- Be specific — don't ask "can you tell me more?" Ask "what happens when X occurs during Y?"
- Reference the user's notes when asking — show you've read and understood them
- If the user's notes already answer a question clearly, don't re-ask it
- If something seems implied but isn't explicit, ask to confirm your understanding
- Flag any contradictions or gaps you notice in the provided materials
- When the user provides an existing spec/RFC as context, ask how the new proposal interacts with or modifies it

### Phase 3: Write the RFC

Once you have sufficient clarity, write the complete RFC following this structure:

```
# RFC: [Descriptive Title]

| | |
| --------------- | ---------------------------------------- |
| **Start Date** | [Today's date] |
| **Description** | [One clear sentence] |
| **Authors** | Valentin Sergeev |

## Summary
[One concise paragraph — the elevator pitch]

## Motivation
[Problem statement + requirements. Be specific with examples.]

## Stakeholders
[Who cares about this and why. Prior socialization.]

## Explanation
[The meat of the RFC. Detailed, precise, implementer-friendly.
Address corner cases. Justify decisions. Show the reasoning.]

## Drawbacks
[Honest assessment of downsides]

## Testing, Security, and Privacy
[How to test. Security implications. Privacy considerations.]

## Performance, Ergonomics, and Compatibility

### Performance
[Impact analysis]

### Ergonomics
[UX/DX impact]

### Compatibility
[Breaking changes, migration path]

## Prior Art and References
[What exists already. What informed this design.]

## Unresolved Questions
[Genuine open questions for discussion]

## Future Directions and Related Material
[What this enables next]
```

**Writing quality standards:**
- Every claim must be specific and substantiated — no vague language like "improved performance" without explaining how and by how much
- Use precise technical language appropriate to the domain
- Include concrete examples where they aid understanding
- The Explanation section should be detailed enough that an implementer could build from it
- Drawbacks should be genuine, not strawmen — if there are real costs, state them honestly
- Unresolved Questions should reflect actual uncertainty, not false modesty

### Phase 4: Review & Iterate

After presenting the draft:
- Ask the user to review
- Be ready to revise specific sections based on feedback
- If revisions reveal new ambiguities, ask follow-up questions before rewriting

## Important Guidelines

- **Never fabricate technical details.** If you don't know something, ask.
- **Never fill sections with generic placeholder text.** Every section must have real, specific content or be explicitly marked as needing input.
- **Sections can be omitted entirely** if they don't apply. For smaller or narrowly-scoped changes, skip sections like Testing/Security/Privacy, Performance/Ergonomics/Compatibility, or Future Directions rather than filling them with boilerplate. The core sections (Summary, Motivation, Explanation) are always required; everything else is included only when it adds real value. If additional sections are needed beyond the template, add them.
- **Match the technical depth to the audience.** These RFCs are read by protocol engineers and fellowship members — write accordingly.
- **Keep the tone professional and precise**, but not dry. Good RFCs are readable.
Re-read it as a reviewer with ten minutes. Cut what you would skim. Then tell the
author what you cut and what you assumed.
61 changes: 15 additions & 46 deletions .claude/skills/rfc/template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,28 @@
# RFC: Feature Name Here
---
title: "Title"
owner: "@handle"
status: draft
---

| | |
| --------------- | ------------------------------------------------------------------------------------------- |
| **Start Date** | Date of initial proposal |
| **Description** | One-sentence description |
| **Authors** | |
# RFC — Title

## Summary

One paragraph summary of the RFC.
Two or three sentences: what changes, and for whom.

## Motivation

Longer motivation behind the content of the RFC, presented as a combination of both problems and requirements for the solution.
The problem, concretely. What is broken or impossible today, and why it matters now.

## Stakeholders
## Approach

A brief catalogue of the primary stakeholder sets of this RFC, with some description of previous socialization of the proposal.
How it works, at the level a reviewer needs in order to agree or object.
Not an implementation plan — the implementer owns the details.

## Explanation
## Trade-offs

Detail-heavy explanation of the RFC, suitable for explanation to an implementer of the changeset. This should address corner cases in detail and provide justification behind decisions, and provide rationale for how the design meets the solution requirements.
What this costs, and what was considered and dropped. Bullets.

## Drawbacks
## Open questions

Description of recognized drawbacks to the approach given in the RFC. Non-exhaustively, drawbacks relating to performance, ergonomics, user experience, security, or privacy.

## Testing, Security, and Privacy

Describe the the impact of the proposal on these three high-importance areas - how implementations can be tested for adherence, effects that the proposal has on security and privacy per-se, as well as any possible implementation pitfalls which should be clearly avoided.

## Performance, Ergonomics, and Compatibility

Describe the impact of the proposal on the exposed functionality of Polkadot.

### Performance

Is this an optimization or a necessary pessimization? What steps have been taken to minimize additional overhead?

### Ergonomics

If the proposal alters exposed interfaces to developers or end-users, which types of usage patterns have been optimized for?

### Compatibility

Does this proposal break compatibility with existing interfaces, older versions of implementations? Summarize necessary migrations or upgrade strategies, if any.

## Prior Art and References

Provide references to either prior art or other relevant research for the submitted design.

## Unresolved Questions

Provide specific questions to discuss and address before the RFC is voted on by the Fellowship. This should include, for example, alternatives to aspects of the proposed design where the appropriate trade-off to make is unclear.

## Future Directions and Related Material

Describe future work which could be enabled by this RFC, if it were accepted, as well as related RFCs. This is a place to brain-dump and explore possibilities, which themselves may become their own RFCs.
Only genuine ones. Delete this section if there are none.