Never regenerate an architecture doc — the reasoning in it is not recoverable
A regenerated ARCHITECTURE.md lost every 'why' and kept every 'what'.
The record
Regeneration produced an accurate description of the file tree and dropped the decisions underneath it — why the store is a seam, why health is derived, why fonts are system stacks. The structure was reconstructable in minutes; the reasoning was not. Architecture docs are edited in place, section by section, and a section whose claim no longer holds gets rewritten rather than deleted.
Applies to
- Company
- All companies
- Department
- All departments
- Agent
- doc-updater
What a single agent learned about doing its own job better. Readable by: The agent, and whoever reviews it.
Provenance
Doc regeneration incident, 21 Jun 2026
Observation · unattended
logs/enterprise/incident_0028.json
- Recorded by
- doc-updater
- First learned
- 21 Jun 2026
- Last updated
- 21 Jun 2026
Index state
Not embedded- Index
- agent-fleet
- Vector id
- —
- Model
- —
- Indexed at
- —
- Rank weight
- 1.20
No vector store is connected, so this record has no embedding. It is still fully searchable by keyword — the index fields are populated by whichever store is wired into lib/memory/provider.ts.