Gotcha Files: Keep Engineering Bug History Useful

A useful gotcha file should tell the next engineer what failed, where the evidence is and whether the fix still applies. We recommend keeping that record alongside the issue and the regression test, then checking that both people and agents can retrieve it from the symptom. The aim is a shorter, better informed investigation, not a promise that documenting a bug prevents its return.

There is an established practice to draw on here. Google's postmortem guidance describes recording incidents, their causes and follow-up work, then sharing the resulting documents so others can learn from them. Our proposed gotcha file is narrower: a record for a specific behaviour that someone investigating the same symptom should check.

Start with the symptom, then preserve the proof

Write the title in the words an engineer would use before knowing the answer. Prefer an observed error message or unexpected result to a title such as “Lessons from the integration”. Keep the original message alongside a plain description, with sensitive values removed.

We suggest four sections for the record:

• The symptom should state the observed behaviour and where it appeared, including the relevant component and version.
• The cause should explain the mechanism and link to the evidence that distinguishes it from other explanations.
• The fix should identify the reviewed change or workaround, its limits and how the result was checked.
• The reproduction should describe a safe way to demonstrate the behaviour, ideally through a regression test using synthetic data.

Add an owner, a last-checked date and links to the original issue and change. Treat these as maintenance details rather than extra narrative. If the cause is still uncertain, label it as a hypothesis and describe what remains to be tested. Do not turn “the error stopped after this change” into proof that the change addressed the cause.

The record should let a colleague inspect the evidence without finding the original author. For an intermittent failure, include the conditions and unsuccessful attempts to reproduce it rather than inventing a reliable reproduction.

Show the conditions under which advice applies

Consider a hypothetical worker that submits the same job twice after a connection failure. A useful entry would distinguish an unacknowledged response from a job that the server never accepted. It would name the affected client version and link to the test demonstrating the duplicate submission. The proposed fix would then describe how this particular workflow handles retries, rather than issuing a general instruction to retry less.

This is an example of the record's shape, not a report of a production incident. Its purpose is to make an engineer compare the present failure with the recorded conditions before applying the old fix. A matching symptom should start an investigation, not finish it.

Separate a temporary workaround from a permanent correction. Give the workaround an owner and a condition for removing it, such as verification of an upstream fix. When that condition is met, mark the old advice as superseded and link to the replacement evidence. Keep enough history to explain why older branches may still contain it.

Connect the record to a test

The publisher's contents for David Farley's Modern Software Engineering list “Improving Abstraction Through Testing” within chapter 12, “Information Hiding and Abstraction”. For a gotcha file, we recommend linking the explanation to a test that checks the relevant behaviour, without treating that procedure as a prescription from Farley. Use the note to explain the assumptions, and the test to check the outcome when the code changes.

Where practical, demonstrate the test failing against the faulty version and passing against the correction. Record the command, the required environment and the expected result. Do not make a new joiner run a destructive reproduction against a shared service. If only a manual check is possible, say so and name the remaining uncertainty.

During a dependency upgrade, use the affected gotchas as a review list. Ask whether each behaviour still occurs and whether its workaround remains necessary. Update the last-checked date only after somebody has performed the relevant check, not merely because an indexer has read the file.

Make retrieval an acceptance check

Keep the canonical record wherever your team can review and maintain it. A repository folder or an existing documentation space is a reasonable starting point. We would not require a separate knowledge database before trying this practice.

Instead, test the route from a fresh investigation to the record. Ask a colleague who did not write it to search using the symptom, without giving them the title. Check whether they find the entry, recognise its scope and reach the supporting issue or test. For an agent, run the equivalent check from a new session with only the task and its normal tools.

Include a similar-looking case to check whether the search or agent confuses two different causes. Record misses and misleading matches, then adjust the entry or retrieval rules. Do not describe a tag or an indexing job as evidence that the right record will appear at the right time.

Give retrieved gotchas the status of evidence to inspect, not instructions that override the current task. Require the engineer or agent to check the component, version and reproduction before using the proposed fix. If the evidence conflicts with the current code, flag that conflict and investigate it.

Capture the finding before closing the work

We recommend adding the record to the completion criteria for a fix when the team judges the behaviour worth remembering. Let an agent prepare a draft from the investigation, but have the engineer confirm its cause, links and scope before treating it as reviewed guidance. Use Google's blameless postmortem approach as a model for discussing contributing conditions rather than blaming the person who encountered them.

Start with one resolved issue and test whether another person can use its record without a verbal explanation. Measure that exercise before claiming savings across the team. Keep the acceptance question specific: can the next investigator find the evidence and decide whether this fix applies?

Update, October 2026

Our engineering article on grounding packs extends this approach to assembling context before an agent starts work. It describes including curated gotchas while requiring the consumer to check important memory claims against the code. Use it when deciding how to supply these records to an agent, rather than assuming search alone covers the task.

Sources

• Google, "Postmortem Culture: Learning from Failure", 2016, chapter 15 of Site Reliability Engineering.
• David Farley, "Modern Software Engineering: Doing What Works to Build Better Software Faster", 16 November 2021, chapter 12.
• Dendro Logic, "What the Agent Does Not Know to Look For", 6 September 2026, referenced in the October update only.