Record and revisit uncertain engineering decisions

Without the original claim and alternatives, a later reviewer can only repeat the earlier confidence. An empty log or all-fine result warrants sampling, not an automatic claim of dishonesty.

Follow-up 1 · The author leaves

A different engineer inherits the debt entry. What needs to survive?

Follow-up 2 · The assumption changes

The GET becomes a billable provider operation. Does the old “safe retry” verdict still apply?

Record the evidence and limitations

Build in three stops: reproduce the small case and baseline failure. Implement the protected boundary. Then replay both changed requirements with captured outputs. Record commands, fixtures, and observed results in your implementation README. A diagram is a prediction until those checks run.

Bring one independently replayed decision and its falsifying input. Additional lead scope: Define review cadence and protect uncertainty reporting from punitive metrics. Completion demonstrates practice evidence. It does not establish interview readiness or multi-team delivery experience.

Detailed implementation and AI-assisted prompts

You end up with a week of recorded acceptances and three counts you cannot get any other way: how many were fine, how many were debt, how many were wrong.

Build

The DECISIONS.md the section told you to start, run as a full loop: one line at every moment you accept something you do not fully understand, across a week of real Stage 1 reading-list work — then a revisit that ends each entry as fine, debt or wrong, with an action attached. The deliverable is the three counts.

The thought process

The first decision is the bar for "did not fully understand", and both failure directions are real: too strict and you are logging every line, which lasts a day. Too loose and the log stays empty, which reads as competence and is actually blindness. The workable bar — log it if, had this been wrong, you would not have caught it. And an entry has to survive a week, because its reader is future-you, who has lost this context. "Accepted the retry logic" is dead in seven days. "accepted that retrying the fetch is safe because it is claimed idempotent — did not verify" can be reopened by a stranger. Future-you is a fresh session with no context, the same reader the spec in project one had.

Third: the revisit must not be re-reading and nodding — you will agree with yourself, the same instrument measuring twice. So verdicts cost something. Fine: you can now explain why it is right. Debt: you still cannot, and a ticket or test now exists. Wrong: it was incorrect, is fixed, and you wrote down what would have caught it sooner. The loop only works if an entry is cheaper than pretending to understand — one line, no shame attached. A log kept to look good measures nothing.

How to organise the prompts

1 — instrument the moment of acceptance, every slice.

List everything in this change I accepted without questioning:
defaults you chose, libraries you picked, behaviour you inferred
from my silence. For each, one line: the choice, the nearest
alternative, and what would reveal the wrong one.

An empty list is flattery — ask instead for the three most fragile choices. You pick which lines enter the log. The model proposes, the log is yours.

2 — the revisit, one week later, in a fresh session.

Here is an entry from my decisions log, and the current code. State
what the decision assumed, whether this week's changes relied on or
contradicted that assumption, and the one check that would settle
it. End with SETTLED or UNSETTLED. Do not reassure me.

Fresh, because it has no stake in defending last week's choices. Every item must end in something runnable, and you run at least three.

3 — the verdicts are yours. The model gets one job.

Argue the strongest case that this entry was WRONG, citing the code
as it is now. One paragraph. If the case is weak, say it is weak.

Use it on anything you are about to mark fine. An entry that survives the strongest opposing case, with the checks run, has earned it. Then count.

On AWS

DECISIONS.md in git is the right store: the log must live where the diff lives, commit with it, and get reviewed with it. DynamoDB is the neighbour, and it earns a place only when the log spans many repositories and you want "all unresolved debt older than thirty days" answered across a team — partition key the repository, sort key the date, that is the entire schema. The revisit needs a schedule, and the honest tool is a calendar entry. The AWS version — EventBridge Scheduler invoking a Lambda that opens an issue listing week-old entries — is worth building once the team is bigger than you.

What productionising it means

The log becomes provenance: the next person reads it and learns which parts of the codebase are load-bearing guesses, which no amount of clean code communicates. The counts become a gauge — a wrong count that is not shrinking means the acceptance bar is too low. An empty week means the bar drifted, not that you suddenly understand everything.

The learning

The section quotes a trial in which developers believed they were faster while measurably being slower. That gap closes with a record, not with effort. The ratio of fine to debt to wrong is a measurement of your own judgment, and until now you were running on the feeling of it.

How you would know it is wrong

• A week of real work and an empty log. The bar is wrong. The work was not that clean.
• Every verdict came back fine. You graded your own homework — run the strongest-case argument on three and see if they hold.
• Trace one real bug from the week. If the acceptance that caused it is not in the log, the log measures diligence, not risk.
• An entry you cannot act on at revisit — "accepted some async stuff" — failed the future-reader test. Tighten the template, not the intention.

Back to the ordered project index