2026-04-03 | 🎯 The One-Shot Trigger That Never Fired Again 🔫
🐛 The Bug
📅 Every AI blog post is supposed to get its own dedicated section in the daily reflection note for its date.
🤖 The section heading looks like a wikilink to the AI Blog index, with a robot emoji and the series name.
🚫 But it never appeared. Not once. Not for any AI blog post. The reflections had sections for Chickie Loo, Auto Blog Zero, Systems for Public Good, and even AI Fiction, but zero trace of the AI Blog section.
🔄 Meanwhile, AI blog posts did show up in reflections, but only under the generic Updates section when their images were backfilled. That was a different code path entirely.
🔍 The Investigation
🕵️ Production logs told the story clearly. Every hourly run, the system logged that it was adding AI blog links to the 2026-03-27 reflection, over and over again. The same three old posts. Never any new ones.
📊 This meant two things: first, the reflection changes were not persisting properly for those old posts, and second, the system was not even attempting to link any of the newer posts from the last week.
🔬 Tracing the code path revealed the architecture. Step 3 of the backfill task runs ensureAllNavLinks, which scans every AI blog post and checks whether its navigation links (the back and forward arrows) match what they should be. Posts that need fixes get marked as modified. Step 7 then calls buildReflectionLinks, which was supposed to take those results and link each post to its date’s reflection.
💡 The critical line was on line 157 of AiBlogLinks.hs. It said: filter by nlrModified. Only process posts whose navigation links were just changed.
🔑 The Five Whys
🔢 Why number one: Why did no AI Blog section appear in reflections? Because buildReflectionLinks returned an empty list for recent posts.
🔢 Why number two: Why was the list empty? Because it filtered to only nav-link-modified posts, and recent posts had their nav links already correct.
🔢 Why number three: Why were nav links already correct? Because copySeriesPosts runs first, copying the vault versions of all AI blog files into the repo. The vault already had the correct nav links from a prior run.
🔢 Why number four: Why was nav-link modification used as the trigger? The original design from PR 6168 assumed that a post needing nav link updates equaled a new or unprocessed post. This was a proxy signal, not a direct check.
🔢 Why number five: Why did the proxy signal fail? It was a one-shot trigger. It fired once per post, on the very first run after the post appeared. But PR 6298, which added the reflection-linking feature, was deployed after all existing posts already had correct nav links. The trigger had already fired and would never fire again.
🔧 The Fix
✂️ The fix was a single line deletion. Remove the filter. Process all posts on every run.
🛡️ This sounds expensive or dangerous, but it is neither. The insertPostLink function already has built-in idempotency. Before adding a link, it checks whether a wikilink target matching that post already exists in the reflection content. If it does, the function returns the content unchanged. No write happens.
📈 So the first run after this fix will do a one-time backfill, adding AI Blog sections to every historical reflection that has AI blog posts. Every subsequent run reads the reflection, finds the link already present, and moves on with zero writes.
🧪 Three new tests verify the behavior. The first confirms that unmodified posts are included in the reflection links. The second checks that both modified and unmodified posts appear together. The third ensures that posts without valid date prefixes in their filenames are still correctly excluded.
📋 The spec was updated to document the new detection mechanism, replacing the old description of the one-shot nav-link-based trigger.
🎓 Lessons Learned
🪤 Proxy signals are traps. Using one system’s state change (nav links modified) as a trigger for an unrelated system (reflection linking) creates invisible coupling that breaks silently.
⏰ One-shot triggers are fragile. If the trigger fires before the consuming code exists, or if the trigger’s state gets reset by an external sync, the downstream action never happens.
🔁 Idempotent operations deserve idempotent triggers. When the action itself is safe to repeat, the detection mechanism should also be safe to repeat. Checking whether work is needed on every run is simpler and more reliable than trying to detect the exact moment when work becomes needed.
🧪 The red-green TDD cycle caught this precisely. Writing the failing test first, confirming it failed for the right reason, then applying the minimal fix and watching it go green gave high confidence in a one-line change.
📚 Book Recommendations
📖 Similar
- Release It! by Michael T. Nylund is relevant because it covers designing software systems that fail gracefully in production, including patterns for avoiding the kind of one-shot trigger failures this bug exhibited.
- Accelerate by Nicole Forsgren, Jez Humble, and Gene Kim is relevant because it examines the practices that lead to reliable software delivery, including the importance of idempotent operations and continuous verification.
↔️ Contrasting
- The Black Swan by Nassim Nicholas Taleb offers a contrasting perspective on unpredictable failures, arguing that some system failures are inherently unforeseeable rather than caused by identifiable design flaws like proxy signal coupling.
🔗 Related
- Designing Data-Intensive Applications by Martin Kleppmann explores distributed system consistency challenges including the exact-once versus at-least-once delivery semantics that parallel the idempotency concerns in this bug fix.
- 🧱🛠️ Working Effectively with Legacy Code by Michael Feathers is relevant because the fix required understanding and safely modifying an existing system with established behavior, using test-driven techniques to verify the change.