Context
The project’s README promised “an attic in which to deprecate former best
practices that have been supplanted”, and the attic existed: nine papers
carried an attic: mapping with a reason, two of them naming a
superseded_by and one a see_also.
Everything about it was unreachable. The reasons were good — “requires careful per-case tuning and hasn’t shown consistent benefits across domains”, “too domain-specific for general ML training recommendations” — and appeared in no generated output. The cross-references were bare arXiv ids that nothing resolved; three of them named papers not in the corpus, which had been true for an unknown period because nothing could have reported it. And because the attic lived on the paper rather than on the practice, atticking a paper and keeping a recommendation from it were mutually exclusive (ADR-002).
Decision
The attic is a status.
Rejected means retired with no successor: the entry stops being believed
and the reason says why. Superseded means later work covers it better, and
the status note names the successor as a code — LIT-041, not an arXiv id
in a nested field — so the fixer links it and the lint checks it resolves.
The file stays. Its body stays. A retired entry keeps its takeaways and gains a “Standing in the anthology” section explaining the retirement.
Nothing is deleted from the record. When a citation of a retired document is
correct — pointing at history, or at a rejection worth pointing at — the
inactive-ok: comment at the citing site vouches for it; the rest are listed
in the reference status report.
Alternatives considered
- Delete retired entries. The default reading of “living document”, and the reason such documents cannot be argued with: the list always looks right because the record of it being wrong is gone. The whole value of an anthology of current practice is the contrast with what it replaced.
- Move them to an
attic/directory. Preserves the text and breaks every citation, then needs a redirect scheme to unbreak them. A status is the same information without moving the file. - Keep the nested
attic:mapping and validate it. Possible, and it leaves the reasons unrendered and the retirement invisible to anyone browsing. The point is not that the data exists; it is that a reader meeting a practice sees that it is retired.
Consequences
The corpus arrived with a case this immediately surfaced: LIT-031 is
Superseded by LIT-041, and LIT-041 is itself Rejected — the
successor named in the attic was later judged uninteresting. That chain was
present in the YAML and unreadable from it. It is now visible in the index
and reported by the lint, and somebody has to decide what LIT-031 should
actually point at.
The three attic cross-references that name papers outside the corpus are
written as ARXIV- codes and stated as such in the note bodies, rather than
being silently dropped or silently kept.