# Nested Timers: A Communication Tool for Problem-Solving Work

## The Core Idea

I am building a time tracking tool that captures what problems you work on and when. The key features:

- Track PROBLEMS you are solving, not tasks you are doing
- Nested structure: sub-problems are children of parent problems
- Visual span editor: drag boundaries to adjust times, like editing video clips
- Share visualizations: send a link or screenshot, no explanation needed

## The Communication Problem

When you work on something and it takes longer than expected, people ask: "Where did the time go?"

Right now, you have to:
1. Reconstruct from memory what happened
2. Choose the right level of detail
3. Write it in a way that sounds professional, not defensive
4. Hope you included enough information that they do not ask follow-ups

This takes 15-20 minutes every time, and the result depends on your memory and writing skill.

## The Solution: Data Instead of Narrative

With a span visualization, you just share a link.

The recipient sees:
- Timeline of when you worked on what
- Nested tree showing problem relationships
- Visual proportions showing where time went
- Clickable spans with your notes and descriptions

They can explore at their own pace. Common questions are preemptively answered:
- "Which part took longest?" → They see it in the graph
- "What were the sub-problems?" → They see the tree structure
- "Did you try X?" → They read your notes on that span

## Why Problems, Not Tasks

A task is: "Configure email service"  
A problem is: "Email service returns 500 errors when sending password resets"

Problems capture what you are trying to achieve or fix. Tasks are just actions.

When you track problems:
- The description explains why you are working on something
- Sub-problems show complexity that was not obvious upfront
- The tree structure shows your decision-making process

When someone looks at your timeline and sees you spent 4 hours on "Email service returns 500 errors" with 8 nested sub-problems, they understand the complexity. If they just see "Configure email service: 4 hours" it looks slow.

## The Shape Tells the Story

Different work has different shapes:

**Straight-through work:**
```
Problem A
  └─ 3 hours
```
Simple, focused, no complications.

**Deep investigation:**
```
Problem A
  └─ Sub-problem B
      └─ Sub-problem C
          └─ Sub-problem D
```
Had to solve 3 layers of dependencies first.

**Interrupted work:**
```
Problem A (2 hours)
[gap]
Problem B (1 hour)
[gap]
Problem A (2 hours, resumed)
```
Got blocked, switched to something else, came back.

**Scope creep:**
```
Problem A (stopped)
  Problem X (new top-level, 4 hours)
```
Abandoned original goal, worked on something else entirely.

Each shape tells a different story. With visualization, the shape IS the communication. You do not have to translate it into words.

## Communication Scenarios

### Open Source Maintenance

Put a link on your profile. Users can see:
- You work on this 3-5 hours per week
- You are currently working on Issue #23
- You worked on Issue #19 last week

No status updates needed. The timeline shows you are making progress.

### Technical Disagreements

Colleague says: "Adding that feature should take 2 hours"  
You think: "No, there is hidden complexity"

You do the work. You track it. You send them the visualization.

They see: 10 hours total, 15 sub-problems, each solved in 20-40 minutes (reasonable pace), just way more sub-problems than they predicted.

They update their model. No argument about competence. Just: here is what actually happened.

### Library Feedback

You spend 45 minutes trying to use someone's library. The docs are unclear.

Instead of: "Your docs are confusing" (gets ignored)  
You send: Timeline showing 30 minutes searching docs, annotations of which pages you looked at, where you finally found the answer

Concrete, actionable feedback.

### Manager 1-on-1s: Mentoring on Decisions

You do NOT use this to send status reports. You use it strategically in 1-on-1s to get mentoring on decision-making.

Example: You show them your week. You point to a specific shape and say:

"See this? I got pulled into working on Ticket #45 even though I was supposed to focus on the migration. I want to practice saying no to interrupts. Could you help me role-play: next time someone asks me to work on something urgent, how do I push back?"

Or: "Here are two graphs. Two months ago, I was context-switching constantly. Here's last week - way fewer switches. Whatever I'm doing is working."

This lets you:
- **Point to specific examples** of behavior you want to change
- **Show progress over time** ("I'm self-improving, here's the data")
- **Get concrete advice** on specific decisions, not vague principles
- **Practice skills** you struggle with (saying no, avoiding scope creep)

You control when to show it. Maybe you walk them through it on your laptop. Maybe you show a screenshot. But you're strategic - you pick the moments where having a visual prepared helps make your point.

### The "Went Overtime" Conversation

You're not happy with this week. You got sucked into unexpected complexity. You show them the graph.

"Look at all these sub-problems. I thought this would be 4 hours. It took 12. I'm not making excuses - I want to get better at estimating. Can you walk me through: what would you have done differently when you hit sub-problem #3?"

The graph isn't to solve anything. It's a talking point. It shows: you've thought about this, you've organized the problems, you want to improve.

### Why Problem Descriptions Matter Here

Because you've already done the work to frame things as problems (not just "worked on ticket #45"), you have descriptions ready:

- "Users can't reset passwords" (not "config email service")  
- "JSON decoding takes 500ms" (not "performance optimization")

When you're in the 1-on-1 trying to explain what's important to work on, you're not translating on the spot from "what I did" to "what problem I was solving." You already thought about this during the week.

The work you put into describing problems pays off: the information is cached, ready to use when making a point.

### Understanding Your Own Patterns

After 2 weeks, you look at your timeline. You notice:
- 40% of time goes to dependency issues
- You always underestimate database work
- You start 5 new problems per day but finish 0

These patterns were invisible without measurement. Now you can make better decisions.

## The Never Write Again Vision

Ideal outcome: you never write status updates or explanations again.

Someone asks what you did? Send link.  
Why it took long? Send link.  
What blocked you? Send link.  
Is project maintained? Link on profile.

The visualization is universal. Works for any time span (1 hour to 1 month), any complexity, any audience.

You just track as you work. Visualization generates automatically. Anyone who wants to know looks at it.

## Why Visual Editing Matters

You cannot track perfectly in real-time. You will:
- Forget to start timers
- Forget to stop timers
- Realize later you were working on a sub-problem

Visual editing lets you fix this quickly:
- Drag span boundaries to adjust times
- Nest spans to show problem relationships
- Split spans when you realize you switched problems
- Update descriptions as you understand better

Like editing video clips in Premiere. Fast because you have immediate visual feedback.

At end of day: 20-30 minutes to review and clean up the timeline. Much easier than reconstructing from scratch.

## What Gets Tracked

You create a span when you start working on a new problem. This happens maybe 20-30 times per day as you switch between problems and encounter sub-problems.

You do NOT track individual steps like:
- Read documentation
- Write code
- Run tests
- Fix typo

Those are actions within solving a problem. Too granular.

You track problem boundaries:
- "Document decoding takes >500ms for 10% of requests" (start timer)
- Encounter sub-problem: "How do I measure JSON.parse() time vs class constructor time?" (create nested timer)
- Encounter another sub-problem: "Can I reproduce the slow JSON parsing in a standalone script?" (another nested timer)
- Sibling sub-problem: "Can I reproduce locally? Need script to make HTTP requests and measure timing" (another nested timer)
- Different branch: "What binary encodings are available? Need to research alternatives" (sibling problem)
- Another branch: "How do I load binary data from different sources to test different encoders locally?" (sibling problem)

## The Data Is Queryable

Because it is structured data, you can:
- Filter to show only work on Issue #37
- Aggregate time by problem type
- Find all problems you worked on for >2 hours but abandoned
- See all times you got blocked on dependencies
- Generate different visualizations for different audiences

Text notes cannot do this. You have to read everything and manually extract patterns.

## How It Compares to Alternatives

**vs. Text file / journal:**
- Text: linear narrative, hard to see structure, cannot query
- This tool: tree structure, visual patterns, programmatically queryable

**vs. Brief summaries when asked:**
- Summaries: 15-20 minutes to write, depends on memory, customized per audience
- This tool: 0 minutes, just share link, recipient controls detail level

**vs. Toggl / RescueTime:**
- Those tools: flat list of tasks, no nested sub-problems
- This tool: tree structure showing problem relationships

**vs. GitHub activity / commits:**
- GitHub: only shows completed work
- This tool: shows work in progress, sub-problems encountered, time spent on blockers

## Cost vs. Benefit

**Daily cost:**
- 20-30 minutes tracking and editing throughout the day

**Annual cost if using for 1 year:**
- Daily overhead: 20-30 min × 250 days = 80-125 hours
- Building the tool: 100-200 hours
- Total: 180-325 hours

**Benefits:**
- Never write status updates again (save ~15 min/week)
- Better decisions because you see patterns
- Better communication with managers, colleagues, users
- Credibility in open source (people can verify you are working)
- Data to improve your process

Hard to quantify the benefits precisely. But if you frequently need to explain where time went, and you struggle with verbal/written communication, the tool pays for itself.

## Who This Is For

This tool is for people who:
- Cannot accurately remember what they did hour-by-hour
- Frequently need to explain where time went (manager asks, colleagues ask, users ask)
- Work on multiple projects or explore new domains
- Struggle with writing clear explanations
- Think visually (graphs easier to process than prose)
- Want data to improve decision-making

If you are already good at remembering, explaining, and making decisions, you do not need this.

## Next Steps

I am building this tool because I have these problems. I will document the development process and share what I learn.

If you have these problems too, follow along: [project link]

For answers to common objections, see: [FAQ document](./deep-work-timers-faq.md)