Keeping project lessons useful

A project can contain a careful account of a mistake and still repeat it. The record may be buried in a conversation, separated from the work it concerns, or phrased so broadly that nobody knows when to apply it.

If you maintain a shared workflow, the useful question is what the next person or agent will do differently because the lesson exists. I want a lesson to save someone a discovery they shouldn’t have to make again. That requires more than saving the explanation.

An import rule with a reason

Consider a hypothetical inventory project. An import script treats item codes as numbers. It turns 0042 into 42, even though those codes identify different items in the source catalog. Someone finds the resulting mismatch and repairs the import.

The weakest response is a note saying, “Be careful with imports.” It doesn’t identify the assumption that failed. A more elaborate incident report can fail in the same way if its only home is a chat the next maintainer cannot find.

A useful lesson states that this catalog’s item codes are text identifiers, links to the catalog’s field definition, and explains why leading zeros matter. A test includes both 0042 and 42 and checks that they remain distinct. The import instructions point to that test. An agent working on the importer encounters the rule where it can affect a decision.

That combination has a purpose. The explanation helps a reader understand the mistake. The test checks a specific way of repeating it. The link places the explanation within reach of the next change. None of those pieces needs to reproduce the whole conversation that led to the repair.

The lesson also preserves its limits. It says nothing about the quantity column, which should still support arithmetic. Turning every field into text would spread the remedy beyond the problem that justified it.

Guidance needs a way to expire

Writing down a mistaken lesson can make a mistake easier to repeat. Suppose the first investigation blamed a file format, when the defect was in one importer’s conversion rule. “Never accept this format” would turn an incomplete diagnosis into a continuing restriction. A later session might obey it faithfully and reject perfectly usable data.

I would keep the observation and the inference distinguishable: what happened, what evidence supports the explanation, and where the proposed rule applies. If the cause is uncertain, record that uncertainty. A confident sentence in a lessons file doesn’t settle it.

Some lessons should become automatic checks. Others concern judgment that a check cannot make, such as when to ask someone affected by a decision. Both need review. A workaround tied to a particular software defect should be reconsidered when that defect is repaired. A rule copied from a different project should earn its place under the new project’s constraints.

The wording says a lesson can protect later sessions. It does not say that writing creates permanent protection. Unread guidance, contradictory instructions and a test that no longer runs all break the connection between the record and the work. There is no virtue in making each new contributor read an ever longer file of accumulated commands.

For a lesson worth keeping, I would name the situation that should bring it to mind and the change that should trigger a review. The inventory rule, for example, belongs beside the importer’s field mapping and should be reviewed when that mapping or the source’s identifier definition changes. If the rule is retired, keep the reason for retiring it where a future maintainer can find it. Otherwise someone may rediscover the old incident and bring the obsolete restriction back.