archiving-rfcs
Skill2 starsChanged 41 days agoMITView on GitHub
Use when adding, auditing, pruning, archiving, restoring, or reviewing RFCs in this repository; checks every new RFC for superseded active records, classifies implemented RFCs by future decision value, deletes rejected RFCs that no longer prevent a tempting mistake, and applies the frozen archived/{class} triplet and manifest seal rules.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/rfcs/AGENTS.mdAGENTS.md
- .agents/rfcs/archived/AGENTS.mdAGENTS.md
- .agents/rfcs/implemented/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- documentingSkill
- editing-proseSkill
- finding-simplificationsSkill
- merging-stacked-prsSkill
- pushingSkill
- reviewingSkill
- translating-docsSkill
- trimming-cot-leakageSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Read the RFC rules, the archive instructions, and the applicable active lifecycle instructions before classifying.
- Distinctive: line 24
Proposed — never archive: keep a live proposal active.
- Distinctive: line 26
Rejected — delete: delete the whole triplet when the rejected idea is obsolete, superseded, no longer plausible, or unlikely to prevent …
- Distinctive: line 28
Do not archive toward a quota.
- Distinctive: line 36
Keep implemented RFCs such as: the bilingual pairing contract of roughly 1000 words, a foundational authority.
- Distinctive: line 45
Search for inbound links from active prose.
- Very specific: line 46
Run uv run hdsh rfc seal. Its append-only mode first proves every existing seal still matches, then adds only the new triplet hashes.
- Distinctive: line 48
After the triplet is sealed, never edit, move, translate, reformat, or delete it.
- Very specific: line 52
Run uv run hdsh rfc archive and the focused archive tests (uv run pytest tests/rfc/test_archive.py).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Archive RFCs
Reduce the active decision corpus without erasing history that can still guide work. Judge every RFC semantically; word count and age are discovery aids, never archive criteria.
Read the contracts
Read the RFC rules, the archive instructions, and the applicable active lifecycle instructions before classifying. Use current code, configuration, newer RFCs, and inbound links to establish whether a rationale still owns or constrains anything.
Check supersession when adding an RFC
Every new RFC triggers a scoped audit of active RFCs covering the same decision, mechanism, or rejected alternative. Classify each full or partial supersession while writing the new RFC: archive qualifying implemented triplets in the same PR, retain and cross-link partial supersessions or independently useful rationale, reject obsolete proposals, and delete rejected RFCs that no longer prevent a plausible mistake. Apply the consolidation rule from the RFC rules when the new owner absorbs every unique proposition; do not defer a known match to a later corpus audit.
Classify by future value
Apply these lifecycle-specific outcomes:
- Implemented — keep active: retain an RFC when its rationale, alternatives, negative guarantees, durable-format semantics, ownership boundary, security rule, or reintroduction condition is likely to guide a future change. Length does not matter.
- Implemented — archive: archive an RFC when the shipped decision is complete and its body is unlikely to guide future work, such as a narrow closed fix, a superseded implementation detail, or process history whose current authority is obvious elsewhere.
- Proposed — never archive: keep a live proposal active; if it is no longer worth pursuing, reject it with an honest reason and satisfy the rejected lifecycle format.
- Rejected — keep only as a guardrail: retain a rejection only when the losing proposal remains a tempting, meaningful mistake and the RFC explains why it loses.
- Rejected — delete: delete the whole triplet when the rejected idea is obsolete, superseded, no longer plausible, or unlikely to prevent re-litigation. Repair or delete inbound links.
Do not archive toward a quota. Inspect every RFC in scope, classify analogous groups under one principle, use best judgment for close cases, and record genuinely borderline decisions for the handoff.
Calibrated examples
These examples set the bar; the approximate sizes demonstrate that size is not the test.
Archive implemented RFCs such as: a one-off adapter workaround of roughly 500 words whose mechanism is closed and has no future design leverage; a minor bug fix of roughly 300 words whose current behavior is obvious from the code; completed process history of roughly 900 words whose current authority lives in the document that owns the rule now.
Keep implemented RFCs such as: the bilingual pairing contract of roughly 1000 words, a foundational authority; a negative guarantee while the design temptation it prevents remains plausible; any RFC that states a reintroduction condition, until that condition resolves.
For rejected RFCs: keep one whose losing proposal remains a tempting, meaningful mistake; delete one whose premise a later decision has already resolved.
Archive one implemented triplet
- Move the complete
<rfc>.md,<rfc>.zh.md, and<rfc>.i18n.yamltriplet fromimplemented/<class>/toarchived/<class>/;implementedis deliberately absent from the archive path. Do not translate, reformat, update facts, or repair links inside the RFC. - Make no body edits. Insert only
Archived: YYYY-MM-DDimmediately belowStatus: implementedin both language files, using the archival date and the same value on both sides. - While the triplet still lives under
implemented/, re-record the sidecar for the two metadata-only edits withuv run hdsh pairing record .agents/rfcs/implemented/<class>/<rfc>.md— the pairing corpus excludes the archived tree, so the record must happen before the move. - Search for inbound links from active prose. Redirect them to current authority, retarget them to the archived path only when the historical snapshot is intentionally cited, or delete them. Never verify or repair links out of the archived RFC.
- Run
uv run hdsh rfc seal. Its append-only mode first proves every existing seal still matches, then adds only the new triplet hashes. Runuv run hdsh rfc archiveafterward.
After the triplet is sealed, never edit, move, translate, reformat, or delete it. Archived RFCs remain valid inbound-link targets but are historical snapshots, not authority for current behavior.
Validate and report
Run uv run hdsh rfc archive and the focused archive tests (uv run pytest tests/rfc/test_archive.py); select any additional evidence through pushing.
Report active implemented RFCs kept, implemented RFCs archived, rejected RFCs kept and deleted, proposed RFCs rejected if any, and every genuinely borderline case with its rationale and chosen outcome. Do not claim archived outbound links are valid: the archive gate intentionally never checks them.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

