The Standup Mirror
What did we leave unfinished, and how stale is it — answered from the repo, not from memory.
The ingredients 3 gifts
Pick your depth — take the quick way in, the full walk-through, or the deep build. Same recipe, your call today.
Quick you just need the mirror up before standup
Run census over your tree, worklog over your history, hand both to a short layout script. One page: open work on the left, recent completions on the right.
No server, no database — three small files reading a checkout you already have.
python3 census.py . --marker TODO --marker FIXME --json > open.jsonl
python3 worklog.py . --since "1 week ago" --by day --json > done.jsonl
python3 build_mirror.py open.jsonl done.jsonl > standup-mirror.htmlWorking you want to understand the join
The five parts below walk it: census finds open markers (and the commit that introduced each), worklog folds git history into what shipped, reltime turns every timestamp into '3h ago' or 'Jun 20'.
The piece you build is the ~40-line join that keys the two streams together and lays out the two columns.
Deep you want it honest and diffable
Staleness is measured from the marker's BIRTH commit, not the file's last edit — a file touched daily can hide a TODO that's been rotting for months. That distinction is the whole value; don't lose it.
All three tools are pure over their inputs, so the page is diffable day to day — you can literally watch a TODO age another day. reltime returns null (not a negative label) for a future timestamp, so clock skew shows as a gap, never a lie.
For real use: declare your team's actual marker set (not the defaults), match worklog's window to your standup cadence, and commit the rendered page so the diff IS the standup delta.
The idea
Every standup, someone asks 'where did we leave off?' and the answer comes from memory, which is exactly the thing that fails. These three gifts answer it from the bytes instead. census walks the tree and counts your markers — TODO, FIXME, whatever you define — and says which ones are still open. worklog folds the git history into 'what actually got done.' reltime turns every timestamp into a short human 'when' — 3h ago, Jun 20. Bolt them together and you get a mirror your team looks into before standup: the open work, when it was last touched, in words a person reads at a glance.
The parts + how they wire
census walks the working tree and emits one record per open marker (file, line, the marker text, and the commit that introduced it) → worklog reads the same repo's git log and folds it into per-author, per-window 'what shipped' rows → reltime is the finishing pass over both streams: every raw timestamp becomes '3h ago' or 'Tue' or 'Jun 20' so the readout is scannable. The output is a single page: open items on the left with a staleness word beside each, recent completions on the right. Nothing here needs a server or a database — it is three small tools reading a checkout you already have.
The one piece you build
The join and the layout. census gives you open markers, worklog gives you completions, and you write the ~40 lines that key them together (by file, by author, by window) and render the two columns. reltime does the humanizing so you never format a date yourself.
The technical breakdown
census's marker set is declared, not hard-coded — you hand it the list of tokens that count as 'open' (TODO, FIXME, HACK, or your own), so the mirror reflects your team's actual conventions rather than a tool author's guess. It reports the introducing commit for each marker, which is what lets reltime say how long a TODO has been sitting: staleness is 'now minus the marker's birth commit date,' not 'now minus last file edit' — a file can be touched daily while a TODO in it rots. worklog's window is a parameter (last-week, last-sprint), so the completions column matches the cadence you actually stand up on. All three are pure over their inputs: same checkout in, same page out, so the mirror is diffable day to day — you can literally see which TODO aged another day.
The honest edge
This reflects markers and commits, not intent. A TODO that someone quietly deleted without doing the work drops off the mirror and looks 'done' — census counts what is present, it cannot count what was abandoned. worklog's effort read is derived from commit spacing, an estimate, not a timesheet. The mirror is honest about the repo's surface; it does not know whether the surface tells the truth. That is a feature for standup — it shows exactly what the bytes claim, and the disagreement between the mirror and someone's memory is usually the useful part.
These are ingredients, not instructions you have to follow. Take these parts and cook something — the recipe as written, a variation, or something we'd never have thought of.
Built it, got stuck, or found a mistake? Shea wants to hear it — success stories, questions, and bug reports all land in the same inbox: