The Context-Window Bonfire
The code made it into the repo. The reason it works this way is somewhere in a chat.
What it is
The Context-Window Bonfire is a project that relies on AI chat history as its only record of design decisions. The constraints, rejected alternatives, and agreed behavior remain in a conversation that the next developer or agent may never read. A saved conversation is useful evidence, but it leaves later readers to reconstruct which proposals were accepted and which still apply.
How it happens
You think out loud, the AI responds, decisions get made, code gets written, and you move on. The conversation contains both accepted decisions and ideas that were discarded ten messages later. Nobody extracts which is which. The chat quietly becomes the design doc, change log, and institutional memory all at once.
In an illustrative webhook integration, the team decides that repeated deliveries must not create a second order. The chat also settles where the deduplication key lives and how long it is retained. A later session sees an apparently redundant lookup and removes it. The implementation was available; the contract and reason for the lookup were not.
Why it’s dangerous
A future maintainer can preserve a choice blindly or change it without knowing what it protects. New AI sessions can repeat the same debate and reach different conclusions. The team pays again for decisions it already made, then pays to reconcile the incompatible answers.
Chat retention is not the main issue. Even with searchable history, someone has to distinguish a rejected suggestion from a decision, then check whether a later change superseded it. Exporting the whole conversation preserves the evidence but leaves that work to every future reader.
How to prevent it
Capture consequential decisions while their context is available: what was accepted, why, what was ruled out, and what would make the team reconsider. Ask AI to draft the record, then check it against what was actually decided. A suggestion from the model must not become “accepted” just because a summary sounds authoritative.
Match the record to the decision. A bug fix may need a regression test and a useful commit message. An authentication boundary may need an architecture decision record (ADR). Michael Nygard’s ADR format records context, decision, status, and consequences, and keeps superseded decisions linked to their replacements. Keep current operational instructions in the runbook and enforceable behavior in tests or contracts. Use an ADR for rationale worth retaining; copying every rule into every document creates another consistency problem.
The serious team fix
- Record the decision before the handoff. End a session with consequential choices in a repo document, ticket, or other maintained project record. Link the relevant code and checks so the next person can follow the reasoning without reopening the conversation.
- Make the next session load it. Point repository instructions at the current design records. For the webhook example, make the deduplication contract and its test discoverable from the handler. The test should fail when the lookup is removed. A document explains why the check exists; the test catches the session that skips the document.
- Keep status honest. Distinguish proposed from accepted decisions. When a decision changes, link its replacement. Update the current contract or runbook in the same change as the code. Have AI flag conflicts, but check the result: a neatly generated ADR can become stale as easily as a handwritten one.
Let AI help with the thinking and the write-up. Make sure the next session inherits the decision, not an invitation to have it again.