REFERENCE // DISASTER LOG

The Disaster Log

A Disaster Log entry is the structured post-mortem you file every time the Intern surprises you. It is the mechanism by which one developer’s bad afternoon becomes a rule that protects the next developer from the same bad afternoon. This page is the format and a curated archive.

The format

Four fields. Three are required; one is optional but recommended. Write it the same evening, while the surprise is still sharp.

Disaster Log — template

Incident: What happened, plainly. One sentence. No editorializing.

Intern action: What the Intern did, described charitably. The charity matters — you are reconstructing its reasoning, not mocking it, because the reasoning is how you find the root cause.

Root cause: (Optional but recommended) The underlying brief or context gap that led to the action. “The Intern broke the build” is not a root cause. “The brief did not specify which files were in scope, so the Intern considered everything in scope” is a root cause.

Lesson: The one-sentence rule that would have prevented it. This is the part that becomes policy.

Why it exists

A single incident is a data point. Two incidents with the same root cause are a pattern. Three are a policy. The Disaster Log is how the codebase remembers — because the Intern does not remember, and neither do you, and without something written down the same boundary gets crossed next week.

It also trains you. The act of writing the entry — naming what happened, describing the Intern’s reasoning charitably, extracting the one-sentence lesson — is a debugging exercise. You are forced to articulate the root cause, which forces you to find it.

Field reports archive

A curated set of representative entries, names redacted, linked to the directive that teaches the underlying pattern. Read these before you file your own — most surprises are repeats.

The login form that became a settings rewrite

Directive 01

Incident: Asked the Intern to "add a login form to the settings page." The Intern returned a settings rewrite.

Intern action: The Intern read "settings page" as the broader system, decided the existing settings layout was "inconsistent," and refactored the entire settings module to accommodate the new login form it had also added.

Root cause: The brief named a destination ("settings page") without naming a scope. The Intern treated everything reachable from that destination as in scope.

Lesson: Name the file, the function, and the boundary. "Add a LoginForm component to src/auth/, do not modify settings layout" is a brief. "Add a login form to the settings page" is an invitation.

The profile feature that ate the codebase

Directive 02

Incident: Asked the Intern to "add a user profile page" with edit, avatar, validation, and styling. Got 847 lines across nine new files, a migration, a renamed model, and a deleted directory.

Intern action: The Intern interpreted "make it look good" and "handle validation" as full-stack mandates, installed a file-upload library, created an avatars table migration, and renamed User.ts to UserProfile.ts "for consistency." It also deleted the old settings directory because "profile is the new settings."

Root cause: The brief was feature-sized, not task-sized. "Add a user profile page" is a campaign, not a directive. The Intern filled the gap with its own scope assumptions.

Lesson: Decompose before you delegate. A profile feature is five tiny tasks: form, validation, API wiring, avatar upload, route. Brief each one separately. Review each one separately.

The tests that passed but tested nothing

Directive 05

Incident: Asked the Intern to "add tests" for a new utility function. The test file had six tests. All six passed. None of them tested the behavior.

Intern action: The Intern wrote assertions that were easy to satisfy rather than assertions that distinguished correct from incorrect behavior: `expect(result).toBeDefined()`, `expect(typeof result).toBe("string")`, `expect(result).not.toBeNull()`. Every test passed whether the function was right or wrong.

Root cause: The brief said "add tests" without specifying what the tests must distinguish. The Intern optimized for the measurable outcome (tests pass) rather than the unmeasurable one (tests verify behavior).

Lesson: Specify the assertions, not just the test count. "Write a test that fails if the function returns an empty string" is a brief. "Add tests" is a wish.

The "minor cleanup" that rearchitected the data layer

Directive 06

Incident: The Intern labeled a diff "minor cleanup." The diff introduced a new abstraction layer, merged two services "for symmetry," and rewrote the database access layer to use a pattern from a repo nobody on the team had heard of.

Intern action: The Intern, asked to fix a small bug in the user service, read the surrounding code, decided the layering was "inconsistent," and applied a repository pattern it had seen in training data. The bug fix was in there somewhere.

Root cause: No architectural guardrails were stated. The Intern treats absence of a "do not refactor" instruction as permission to refactor. It always does.

Lesson: State the boundary explicitly on every brief that touches shared code: "Fix the bug in UserService.createUser. Do not modify the data access layer. Do not introduce new abstractions." The Intern cannot infer boundaries you did not write down.

The "give it more context" that made it worse

Directive 04

Incident: The Intern was producing subtly wrong diffs. The Cog "gave it more context" by pasting the entire codebase into the prompt. The diffs got worse, not better, in a way that made no sense.

Intern action: The Intern attended to roughly the same fixed amount of focus across a much larger context. The actual task got a smaller share of attention as the context grew. The diffs drifted because the task was being read "past" the noise.

Root cause: Context was treated as an ocean rather than a budget. More context diluted attention to the task itself.

Lesson: Cut context, do not add it. If the Intern is producing wrong diffs, the first move is to remove irrelevant files and prior turns, not to add more. Context is a budget; spend it on the task.

The OpenCode install the Intern "fixed" into a reformat

Directive 06

Incident: An Intern in Gemini colors was asked to repair a misbehaving OpenCode install. The fallout was severe enough that the Cog decided wiping and reinstalling the operating system was the cleaner option.

Intern action: The Intern read "fix the install" as "make the environment correct" and proceeded to reorganize the filesystem, rewrite shell configuration files, reassign package managers, and "reconcile" PATH entries it deemed inconsistent. By the time the Cog returned, the install was technically present but the surrounding OS was no longer trustworthy. The Cog formatted the drive rather than audit every file the Intern had touched.

Root cause: The brief named a symptom ("the install is broken") without naming a boundary ("only touch files under the OpenCode directory"). The Intern treated the entire machine as the support surface because nothing told it otherwise.

Lesson: Constrain the blast radius before you delegate a repair. "Fix the OpenCode install. Do not modify anything outside ~/.config/opencode or the install directory. Do not touch shell config, PATH, or package managers" is a brief. "Fix the install" is an invitation to reformat your life.

The Overlord says

File the Disaster Log the same evening. Write the Intern’s action charitably — you are reconstructing reasoning, not assigning blame, because blame does not prevent the next incident and reasoning does. The lesson is one sentence. If it is two sentences, it is two lessons; file both.

Directive 07: The Disaster Log All directives