openmove/engineering-design-playbook / .agents/skills/design-docs-template/rfc-hygiene
docs-template-rfc-hygiene
VerifiedHygiene pass on a draft RFC: aligns names, Mermaid diagrams, prose, and examples to one canon; removes stale noise after iteration so readers are not misled. Use before review or close-loop when the RFC grew messy. Invoked via design-docs-template.
| File | Kind | Size |
|---|---|---|
| CHECKLIST.md | markdown | 1.8 KB |
| SKILL.md | skill md | 3.0 KB |
SKILL.md
View on GitHub---
name: docs-template-rfc-hygiene
description: >-
Hygiene pass on a draft RFC: aligns names, Mermaid diagrams, prose, and
examples to one canon; removes stale noise after iteration so readers are not
misled. Use before review or close-loop when the RFC grew messy. Invoked via
design-docs-template.
---
# rfc-hygiene — clean a noisy draft
**What:** Cleanup pass (not a rewrite): one vocabulary, diagrams↔prose↔examples, delete dead options and obsolete “for now”.
**When:** Long-edited draft; renames landed in one section but not others; before merge or **close-loop**.
**Not:** Accepting the RFC (**close-loop**) or starting a blank proposal (**new-rfc**).
## Process
### 1. Pin the canon
Read the RFC end-to-end once. Extract the **canon** — current entity names, renames, closed questions, and “source of truth” tables (constraints, From-table, ER, field boxes).
Completion: a short internal list of canonical names and what they replaced. If two sections disagree on the canon, stop and ask (at most two questions).
### 2. Audit against the checklist
Apply every item in [CHECKLIST.md](CHECKLIST.md). Record findings as concrete locations (heading / diagram / table / example id), not vibes.
Completion: every checklist row is either OK or a finding.
### 3. Report, then edit
Present findings first, grouped:
| Severity | Meaning |
| --- | --- |
| **Blocker** | Reader would trust the wrong model (stale name, diagram≠prose, example broken FK) |
| **Noise** | Closed options, dead “Must discuss”, obsolete “for now / later”, duplicate explanations |
| **Nit** | Wording only; meaning already clear |
Then:
- User said only “check / rivedi / hygiene” → stop after the report; wait for apply.
- User said “sistema / fix / clean it / togli il rumore” → apply **Blocker** + **Noise** in the same turn. Leave **Nit** unless they asked for a full polish.
Edits stay proportional: rename, delete stale paragraphs, fix Mermaid edges, repair example tables. No new sections unless a checklist gap forces a one-line pointer (“see RFC-NNNN”).
### 4. Verify
Re-scan the touched headings and diagrams. Confirm:
- no old name left where the canon forbids it (search the file)
- every Mermaid entity in the overview still has a home in prose or an explicit “unchanged → other RFC” line
- examples still compile against the ER
If the repo syncs docs into a site (`website/scripts/sync-docs.mjs` or equivalent), run sync after edits when a local preview is in use.
Completion: report what changed (bullet list) and what was left as Nit or open question.
## Hard rules
- Prefer **delete** over “comment that this is outdated”.
- Prefer **one term** everywhere; put the old name only in an explicit rename/From table.
- Accepted / frozen RFCs: hygiene is read-only unless the user explicitly reopens them — say so and offer **close-loop** / new ADR + arc42 instead.
- Do not expand scope into new entities or reopening closed Qs unless the inconsistency proves the close was never reflected in the text.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |