About two weeks ago, I introduced the friction log as a tool. Here is what happened when I actually used it. Real entries, real patterns, real findings.
Last time, I wrote about environment design over willpower. The argument was simple: design systems that carry the discipline for you, because willpower depletes but environments do not. I introduced the friction log as one such tool. One line per friction point, date, tag, observation. No judgement, no solutions, just what happened.
That was theory. This is what happened when I actually used it.
The First Two Weeks
The friction log lived in a markdown file inside my brl-subagent project. Every time something went wrong, or felt wrong, or took longer than it should have, I wrote it down. One sentence. Tagged with a category: worktree, workflow, docs, process, tooling. Dated. That was it.
Seventeen entries in the first week. August 1 to August 7.
Some entries were obvious problems. Others were small irritations that I would have normally forgotten by lunchtime. The discipline wasn’t analysing or fixing. The discipline was writing it down before the memory faded.
Here is what a typical entry looked like:
“Post-merge cleanup (fetch, pull, worktree remove, branch delete, sync extension) was done manually ~12x in one sprint.”
That’s it. No explanation of why it happened. No proposal for how to fix it. Just the observation that twelve times in one sprint, I did the same manual cleanup.
The Pattern That Emerged
After two weeks, I reviewed the log. Not to fix anything. Just to see what was there.
One pattern dominated. It showed up in so many entries that I could not ignore it.
Verifying that a mechanism exists is not the same as verifying that it works.
The sync script ran but did not cover the right directories. The warning fired but went to a channel nobody read. The gate existed but grep masked the exit code. In every case, the mechanism was present. The check passed. But the output was not what was assumed.
Take this entry:
“sync-extension.sh did NOT sync templates/ — the 9 builtin templates never reached the installed extension; loadBuiltinTemplates fell back gracefully so the gap was silent.”
The script ran. It completed without errors. The templates were never synced. The system fell back to a default behaviour that hid the failure. If I had not logged it, I would never have known.
Or this one:
“check-repo.sh gap: verifies node_modules PRESENCE not VERSION — main’s install was stale at 0.83.0 since 2026-08-01.”
The check verified that node_modules existed. It did not verify that it was the right version. The check passed. The environment was stale. The mechanism was present. The output was wrong.
This is the kind of bug that code reviews do not catch. Code reviews look at what the code does. They do not look at what the code fails to notice.
What The Review Revealed
When I sat down with the full log, five patterns surfaced beyond the surface level.
Verification of existence, not effectiveness. This was the dominant one. Every mechanism in the pipeline existed. Most of them worked. Some of them did not work in the way they were assumed to work. The log caught the gap between “the check ran” and “the check meant something.”
Recurrence before resolution. The same fix was recommended four times before it was actually implemented. Four times. The log made the repetition undeniable. Without it, each recommendation would have felt like a new insight instead of the same problem coming back.
Misdiagnosis under pressure. CPU contention was diagnosed as the cause of a slowdown. The real cause was a stale SDK version. The log did not catch this in real time, but it provided the data to see the misdiagnosis in retrospect. When you are under pressure, you reach for the most convenient explanation. The log gives you the evidence to challenge that instinct.
Risk calibration oscillation. Full adversarial review on a two-line change, then a merge on a red suite. The log captured both. Separately, each decision might have seemed reasonable. Side by side, the inconsistency is obvious.
The harness is not the product. Several entries documented time spent babysitting the tool instead of letting it run. The friction log caught the moments where I was managing the system instead of using it. That is a pattern I would not have noticed without the data.
The Friction Log Catches What Code Reviews Miss
Code reviews examine what the code does. The friction log examines what the environment fails to surface.
Look at this entry:
“MERGE PROCEED ON A RED SUITE — grep masked vitest’s exit code, so the chain pushed + closed despite ‘1 failed’.”
The code review would have approved the grep command. It is a simple, correct line of code. The friction log captured the consequence: a merge proceeded on a failing test suite because the mechanism for detecting failure was broken.
Or this one:
“Conductor implemented issue #27 directly in the main checkout and pushed to main — no branch, no PR, no review.”
The code review never happened because the code never went through the process. The friction log caught the process failure that made the code review impossible.
The log does not replace code review. It covers a different failure mode entirely. Code reviews catch bad code. The friction log catches bad assumptions about what the system is actually doing.
What I Learned
The friction log does not fix problems. That is not its job. Its job is to make problems undeniable.
Before the log, I knew these problems existed. I could feel them. But the feeling was diffuse, easy to dismiss, easy to forget. After the log, the problems were concrete. They had dates. They had tags. They had sentences describing exactly what happened.
That shift from “I think there is a problem” to “here is the problem, dated and documented” is the entire value of the tool. It does not solve anything. It makes solving possible.
The log also revealed something about my own process. The first few entries took days to resolve. By the second week, the same types of entries were caught within the same session. The log was not just recording friction. It was accelerating recognition. The pattern was becoming familiar enough to spot in real time.
The Minimum Viable Start
If you want to try this, here is the minimum. Open a markdown file. Write the date. Write one sentence about what went wrong or felt wrong today. Tag it if you want to. Do not analyse it. Do not fix it. Just write it down.
Do this for two weeks. Then read it back.
The patterns will be there. You do not need to look for them. They will find you.