Executed Specs Are Decision Records, Not Trash
Executed specifications are decision records: archive them as a status change, keep them immutable with the ADR append-only pattern.
The document tree of a portal project looked crowded. Specifications that had already been executed still sat mixed in with documents currently under development. Finding a living document became slow, and cross-references between specifications were easy to confuse.
The first reaction is usually the same: moving old files around is just housekeeping. The goal is a tidier directory, or more aggressively, stale history can simply be deleted.
What They Actually Are: Decision Records
That view misses the documents' fundamental function. An executed specification is a decision record. It explains why the system is shaped the way it is, which alternatives were rejected, and what trade-offs were accepted at the time. Moving it to an archive folder is not disposal; it is a formal status change from active to historical.
The risk is real in both directions. An old specification left in the active directory is often read by new developers as the latest guidance, and implementations that follow it come out inconsistent. An archive that gets deleted erases the reasoning trail instead. The team is left guessing why an existing configuration is the way it is.
One common example: a specification once fixed a particular slug format at the API boundary. A year later that decision was pulled because of a bug report. Without an archive, a developer reading the old specification would build a new feature on a rule that no longer applies, then spend a whole debugging session discovering they followed the wrong document.
The archive folder resolves both problems at once. Documents do not disappear, but their status is clearly separated from living documents. Anyone reading the archive knows they are reading history, not current instructions.
The Architecture Decision Record doctrine provides a fitting framework for this status change. AWS guidance states that an accepted ADR becomes immutable; when new insight demands a different decision, the team writes a new ADR, and that new ADR is the one declaring it supersedes the old [7].
The Azure Well-Architected Framework reinforces it with the append-only log principle: do not edit an accepted record. Write a new record declaring supersede, then link the two so the history of thinking stays readable and it is visible when the direction changed [8].
Implementation at the file level is simple. Living documents stay in the plans folder, executed documents move to the archive folder, and every replacement specification names which archived document it replaces along with a link. The history stays intact; current status stays clear.
This immutability principle is also what keeps archives free of version confusion. Because an archived document is never edited, a reader does not need to inspect revision history to know what the document contained when the decision was made. One file, one state, with no chance of contents changing quietly behind a link that has already been shared elsewhere.
Two Criteria for Moving to the Archive
The dividing threshold must be objective, not a feeling. Two conditions decide it. First, the specification's implementation is complete and running. Second, there are no active plans to modify that document in the current development cycle.
The second criterion matters as much as the first. A specification that has been executed but is still targeted for the next round of revision should stay in the active folder; the move waits until the wave of revisions settles. That way the archive folder truly holds only stabilized documents, and archive status is never misleading.
The move itself can be as light as shifting files into an archive folder in a single commit, as long as the commit message lists which documents changed status. Teams with stricter audit needs add one status line at the head of the document, for example marking an archive entry as superseded by a specific document, following the same ADR pattern.
When both conditions hold, the document has changed role into a historical reference. Leaving it in the active directory only adds noise. The archive is not a final dumping ground but a reference shelf that guarantees every system decision can be traced back to its logical root.