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.
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. 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: 319k | 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: 196k | 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: 196k | 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: 196k | Updated | Claude CodeCodex | Verified | Install |