Stay Focussed When Debugging Production Issues - The 'Fact Bucket' Method

As a software engineer with ADHD, I've developed a technique to help me stay focussed when debugging production issues and asking questions. It's called The Fact Bucket.

The Challenge: Information Overload During Debugging

Debugging a live production issue, tracing nils through Rails controllers, or untangling a domain model can leave my brain scattered in twenty directions. Especially given I’m neurodivergent. I spot something odd — a controller skipping a check, a field that’s nil when it shouldn’t be — and I think, “I’ll come back to that.”

But I don’t. And what’s more, it distracts me.

And later, when everything collapses, I would think:

Oh yeah, I remember - I saw something weird.

I was diagnosed with ADHD in adulthood. The diagnosis made a lot of things click — especially why I’d dive deep into debugging but forget half the interesting things I noticed along the way.

Debugging with ADHD means balancing hyperfocus with distractibility. If I pause every time I see something "interesting," I lose momentum. But if I don’t note it down, it's gone. That tension led me to a system I now teach every engineer I coach.

The Solution: The "Fact Bucket"

I call it the Fact Bucket. It's a simple idea:

• Capture interesting observations immediately

• Don’t interrupt your current flow

• Review the patterns later

This isn’t a formal tool. It can be a fact_bucket.md in your repo. A Notion doc. A sticky note. Whatever works. The key is — when your Spidey sense tingles, you log it and keep moving.

This fact bucket can be reviewed regularly. As I move through a debugging session with a production defect, I record facts that are pertinent to the issue and facts that are not. Either way, it allows me to build a picture of the app in my head.

Case Study: Spotting Nils & Domain Inconsistencies

Recently, I gave a coaching session with Petro Yakubiv on his restaurant app built in Rails. Customers were scanning QR codes to view menus. Sometimes they’d see... nothing. But no errors were thrown. Petro wanted to know how to get started with observability.

Inside the controller, we spotted safe navigators like @menu&.name and @table&.zone. That meant @menu or @table could be nil.

I noted this in the fact bucket: “table and menu possibly nil – investigate default paths and fallbacks.”

Later, it turned out if a restaurant admin disabled all menus by accident, customers would land on a menu-less screen. No crashes. Just silent failure. That allowed us to come up with ways of mitigating against these kinds of failures by logging relevant events.

Using The Fact Bucket With Steps To Observable Software

Below is the process I use for all my debugging.

I’ve evolved it over years of exploration with real production systems.

A quick recap:

1. Question - Form a hypothesis about what might be going wrong and form a specific question you want answered.

2. Decide - Figure out what data can you collect that answers the question.

3. Build - Create instrumentation in code to collect the data

4. Use - Logs, graphs, traces, use your observability tool to explore the data and ask the question

5. Reflect - An opportunity to reflect on your progress and next steps. What have you learned? Are you still going in the right direction? What’s the next step?

How does the fact bucket work at each step?

1. Question - evolve the next question or hypothesis using the fact bucket

2. Decide - not relevant

3. Build - not relevant

4. Use - collect facts in the bucket

5. Reflect - review the bucket and use it to help you decide what to do next

The fact bucket works beautifully with the Steps To Observable Software - it keeps me on track and focussed on the job at hand.

Broader Applications: Code Reviews, Architecture, Client Calls

I now use the Fact Bucket method everywhere:

• During code reviews, I jot down odd patterns instead of derailing the main feedback.

• In architecture discussions, I log confusing constraints to clarify later.

• On client calls, I capture “that weird thing they said” without breaking the conversation flow.

It's the perfect buffer between noticing and acting.

Tools and Techniques: Keeping Your Fact Bucket Simple

You don’t need a system. Just habits.

• Use bin/fact-bucket to open a Markdown file in your project

• Create a GitHub Gist or Notion page called 🧠 Fact Bucket

• Use VSCode’s TODO extension and prefix with FACT: instead of TODO:

The best tool is the one you’ll use without friction.

Turning Cognitive Challenges into Debugging Superpowers

My forgetfulness isn’t a flaw — it’s a clue that my brain is noticing more than it can handle at once. The Fact Bucket turns that chaos into leverage. I start to spot patterns others miss. I connect threads across time.

Next Steps

1. Sign up for free coaching

I’m currently offering free observability coaching sessions of 90 minutes.

I’ve got 5 slots available a month for a limited time.

DM me on LinkedIn with COACH and I’ll give you more details.

2. Join the waitlist for my course

I’m preparing a real world, hands on practical course on observability and the first module will be FREE.

DM me on LinkedIn with COURSE and I’ll let you know when it’s out.