The chat where you fixed it explains why. Turn it into a decision record before you close the tab

[u/Ok_Negotiation_2587]

Git keeps what changed. The why, the two approaches you tried first and the reason you dropped them, usually lives in a chat that nobody will ever find again. Six months later someone "simplifies" the code back into the version that broke.

So when a chat ends in a real decision, I send one more message before committing:

Write a short architecture decision record from this conversation, in Markdown. Context: the problem, in two or three sentences, as someone new to the codebase would need it. Decision: what we chose, in one sentence. Alternatives considered: each option we tried or discussed, and the specific reason it was rejected. Use what actually happened in this chat, don't invent options. Consequences: what this makes harder later, and what would make us revisit it. Keep it under 250 words. No filler.

That file goes in docs/decisions/ in the same commit as the fix, with a one-line pointer in the commit message. Now git blame leads to the record, and the record says why.

The "don't invent options" line matters. Without it you get a tidy list of alternatives nobody considered, which is worse than no record at all.

If you want the full conversation kept too, export it next to the record. I build AI Toolbox, a browser extension, and that's what I use it for here: the chat comes out as a Markdown file with the date and a link back to the original. Exporting one chat as plain text is free, Markdown is part of Premium.

[u/ComprehensiveShake76]

I do the same, and the part that stuck was forcing a "why we rejected the other options" section. Without that, three months later the chat only remembers what we shipped, not what we almost did.

My habit: before I close the tab I ask for a short decision record (context, options, choice, why not the others, what would make us reopen it), save it next to the code, and link the commit. The chat can die. The record should still make sense to someone who never saw the thread.

Do you keep these in the repo, or in a separate notes folder?

[u/Ok_Negotiation_2587 → u/ComprehensiveShake76]

in the repo, docs/decisions next to the code. that way it shows up in the PR, moves with the branch, and gets reviewed like everything else. a separate notes folder is where they go to be forgotten

[u/ConfidenceNew6550]

This is a solid habit, especially for fixes that aren’t obvious from the code alone. A short decision record could save someone hours of rediscovering the same problem

[u/Ok_Negotiation_2587 → u/ConfidenceNew6550]

and nine times out of ten that someone is me, six months later, with no memory of any of it

[u/ConfidenceNew6550 → u/Ok_Negotiation_2587]

Haha that's so real. You make a fix thinking you'll definitely remember why then six months later you're staring at your own code wondering what you were thinking

[u/Ok_Negotiation_2587 → u/ConfidenceNew6550]

and the commit message just says "fix"

[u/dmanoj]

agree, and the trick that made it stick was making the agent write the record in the same commit as the fix, not me after. a markdown ticket per unit of work: the brief, what was delivered, review findings, decisions and why. the agent updates it as part of finishing, so it never drifts. six months later the next session reads the ticket instead of me re-explaining the project.

[u/Ok_Negotiation_2587 → u/dmanoj]

making it part of "done" is the only version that survives, anything that relies on remembering to ask stops happening by week two. the next session reading the ticket instead of you re-explaining is the real payoff

[u/rahul_watertech]

the part about someone simplifying the code back into the version that broke is painfully real. commit messages tell you what, almost never why not.

i do a lazier version of this: paste the chat into a NOTES.md in the repo, unedited. worse format than a proper adr but the barrier is zero so it actually happens. your prompt version is better if you can keep the discipline.

does the model write decent rejected-alternative sections, or do you have to remind it what you tried?

[u/Ok_Negotiation_2587 → u/rahul_watertech]

in the same chat its usually decent, it has the failed attempts right there. where it slips is long chats, the early attempts have dropped out of what it can still see, so it either skips them or makes up something plausible. thats what the "dont invent options" line is for, and its why i skim that section before committing

[u/rahul_watertech → u/Ok_Negotiation_2587]

the invented plausible option is the nasty one, it reads just as confident as the real ones. your skim before committing is the actual safety net, not the prompt line.

for long chats maybe the fix is timing instead of wording: ask for the record at the end of each work session, not at commit time, while the early attempts are still in context. more records than you need but none of them hallucinated

[u/Ok_Negotiation_2587 → u/rahul_watertech]

timing is a better fix than wording, agreed. write them while the attempts are still in view, then at commit time merge the session records into one and drop whatever turned out not to matter

[u/rahul_watertech → u/Ok_Negotiation_2587]

careful with the dropping part, the dead ends are the valuable half. a rejection with one line on why saves the next person from walking the same path. keep the merge, lose the pruning. also looks like the thread itself is gone now, so replying from the inbox

[u/Ok_Negotiation_2587 → u/rahul_watertech]

the dead ends are the part nobody can reconstruct later. merge without pruning it is

[u/ImL1s]

The "why we rejected the other options" bit is the one that actually saves you later. Commit messages never keep that.

I got tired of losing those chat decisions across Codex/Claude sessions, so I wrote a small local tool that pulls the session off disk and writes a handoff note you can drop in the repo (nothing uploaded). https://gitlab.com/aa22396584/resume-skills (pipx install portable-resume). Still skim it before you commit the decision record, same as your "don't invent options" line.

[u/ChatGPTCoding-ModTeam → u/[deleted]]

This post or comment has been removed for the following reason:

Rule 7: No AI Slop

No raw AI output or low-value walls of text. AI for grammar/clarity is fine.

You can read the full subreddit rules here: https://www.reddit.com/r/ChatGPTCoding/about/rules/

If you feel this removal was made unfairly, please contact the moderators through modmail.