A weekly review for engineers that isn't about tasks

The classic weekly review (from Getting Things Done) is about tasks and commitments: empty your inboxes, update your lists, look at your calendar. That's useful, and your issue tracker probably covers most of it already.

What it doesn't cover is the stuff developers lose all the time: why you picked that library, what the fix was for that weird timezone bug, which config flag finally made the build work. You solve a problem, move on, and meet it again six months later with no memory of the answer.

This is a review built around that problem. It has two parts: a tiny daily habit and a fixed weekly session, plus an optional monthly skim.

During the week: one line per thing worth remembering

Keep a section in your daily note (or a single running file, if you don't do daily notes) and add one line whenever something happens that you'd be annoyed to rediscover:

• a bug that took more than half an hour to understand,
• an API or library that didn't behave the way you assumed,
• a choice between two approaches,
• a command, flag or config you had to look up.

Keep the format dumb so you actually do it:

## Log
- Postgres: ILIKE treats `_` and `%` in user input as wildcards. Escape them before building the pattern. PR #412
- Chose server-side sessions over JWT refresh; token rotation raced across tabs. -> needs decision note
- `git log -S "term"` finds when a string first appeared. Keep forgetting this.

Problem, answer, link if there is one. No tags required, no templates to fill in. If you're adding more than a couple of minutes a day, you're overdoing it.

Friday: 45 minutes, same questions every week

Put it on your calendar. Friday afternoon works for most people because the week is still fresh and it's rarely prime focus time anyway. Open the week's log lines and go through four questions.

1. What happened more than once?

Scan for repeats. Same kind of bug twice, same lookup twice, same review comment on two PRs. A repeat is a signal that a small artifact would pay off:

• a snippet you can paste next time,
• a checklist (e.g. "things to check when a query gets slow"),
• a lint rule or test that stops it happening again,
• a line in the project README.

Make the artifact now, while you remember the details. Don't make one for things that only happened once; most of those never come back.

2. What did I decide?

Any line that's really a decision (you picked X over Y and there were trade-offs) gets promoted to its own note with context, options and reasons. It takes ten minutes on Friday and saves the "why on earth did we do this" conversation later. If you link decisions to commits, add the ID to the relevant commits now.

3. What did I have to look up, and should I actually learn it?

Things you looked up once are fine. Things you looked up three times are a gap. Keep a short "learn next" list, and be honest about priority: only put something at the top if it keeps costing you time. A line like this is enough:

## Learn next
- Postgres window functions (hit twice this month writing reports)
- TypeScript conditional types (fought inference on the API client again)

Then actually block time for the top item. An hour of reading the docs properly beats another three rounds of copying from Stack Overflow.

4. What's still open?

Last: anything from the log that's unresolved. A workaround you shipped that needs a real fix, a question you never answered, a follow-up from an incident. Turn each into a task in whatever tracker you use, or delete it if you honestly won't get to it. The point is that nothing unresolved lives only in the log.

The weekly note

The output of all this is one short note per week. A template like this keeps it consistent:

# Week 2026-W39

## Repeats -> artifacts
- ILIKE escaping: added `escapeLike()` helper + test

## Decisions
- [[adr-20260924-session-store]]

## Learn next
- Postgres window functions

## Open -> tasks
- Replace retry workaround in webhook handler (#431)

## One sentence on the week
Mostly auth work; lost a day to the tab race before understanding it.

If a section is empty, leave it empty. Some weeks nothing repeats and you decide nothing interesting. That's fine; the review takes fifteen minutes those weeks.

Once a month: skim, don't audit

On the first Friday of the month, spend an extra twenty minutes reading the last four weekly notes in a row. You're looking for things that only show up at that distance:

• the same area of the codebase appearing in "repeats" every week (a refactor candidate),
• a "learn next" item that's been sitting at the top for a month (block the time or drop it),
• decisions that contradict each other.

Write two or three bullets at the top of the month's first weekly note and move on. No spreadsheets, no scoring yourself.

Why it's built this way

The usual failure mode of review systems is that they're more work than the problems they solve, so they get dropped after a few weeks. This one tries to avoid that:

• Capture costs almost nothing. One line, no structure, in a note you already have open.
• The weekly session has fixed questions. You're never staring at a blank page.
• Every question produces something concrete (a snippet, a decision note, a task) or produces nothing and you move on.
• There's no metric to maintain. Tracking "hours saved" by your notes is itself a job, and the numbers are guesses anyway.

Getting started this week

1. Add a ## Log section to today's daily note (or create log.md).
2. Add one line every time something annoys you or surprises you.
3. Put a 45-minute block on Friday and run the four questions.

Skip the monthly skim until you've done four weekly reviews. If you only ever do the Friday part, you're already ahead of where most of us are.

Dev Second Brain, my Obsidian vault for developers, includes a weekly review template, if you'd rather start from one than build it yourself.