Keep the Plan Beside the Code: Debugging with HDD Light

In my earlier article about my dad's workbench, I wrote about his work as a precision sheet metal mechanic. He kept drawings at his workstation and corrected them when the job required a change. The next person had a record that reflected the work.

I keep coming back to that lesson when working with coding agents. We agree on a plan in chat, start investigating, and discover that the first explanation was wrong. If the new evidence stays in the conversation, the story can still describe a plan we've already abandoned.

HDD Light gives a small bug investigation a place to keep that evolving understanding. It's lightweight hypothesis-driven development: describe the problem and the observable improvement, agree on a small plan, record what happens, and decide what to do next.

This walkthrough uses the HDD Light template in imdone Workbench. We'll create one bug story, start HDD from its Agent tab, and keep the plan and evidence with the investigation. The example is illustrative; it isn't a recorded product defect or an executed test.

1. Open Workbench and create a local story

You'll need Node.js 22 or newer, imdone-cli, and Codex or Claude Code installed and signed in for the agent workflow below. You can read and edit stories without an agent, but starting HDD uses your configured coding agent.

From your project directory:

npm i -g imdone-cli
imdone work

First-run setup used to be a detour: you had to initialize the project outside Workbench before it could open a usable board. An unconfigured directory now opens guided setup inside the app. Choose a provider, configure it, review what will happen, and initialize through to your board.

For this trial, choose Filesystem. It lets you keep the bug story locally without a Jira or GitHub account. An already configured project opens its existing board.

Choose Board actions → Add story. Give the bug a specific title, such as “Search results duplicate after a second refresh,” and select the HDD Light template. Choose the Filesystem provider if the project has multiple providers, review, and create the story. Keep its actual issue key rather than assuming a particular number.

2. Use the template to define what better means

Open the story's Files tab. HDD Light keeps the main record small:

• Problem: what fails, and what would be observably better?
• Current Plan: what should happen next, the outcome, feedback path, evidence capture, and whether the plan is approved.
• Progress notes: a linked chronological record of observations, decisions and next steps.
• Closeout: where the change is live, what happened, and whether to close, iterate or pivot.

For our illustrative search bug, the template could begin like this. The plan is deliberately unapproved and the closeout fields are pending:

## Problem

Refreshing the same search twice displays duplicate rows.
A better result is one displayed row per result ID after each refresh.

## Current Plan

First reproduce the duplicate rows. Compare the API response with the
client state, then propose the smallest change supported by that evidence.

**Observable outcome**: repeated refreshes display each result once.

**Feedback path**: retry the original flow and report duplicates or any
unexpected change in how results update.

**Evidence/data capture**: retain reproduction steps, relevant response/state
observations, and the actual before-and-after verification results.

**Plan approved**: No

[Progress notes](./attachments/progress-notes.md)

## Closeout

**Deploy evidence**: Pending.

**Result or feedback**: Pending verification of the original flow.

**Close / iterate / pivot decision**: Pending evidence.

This gives you and the agent a concrete behavior to investigate. It also leaves room for the first explanation to be wrong.

3. Start HDD from the story's Agent tab

Open Agent → Start HDD. The agent infers lightweight mode from the HDD Light template; you don't need to select the mode again in chat or launch a separate HDD command in the terminal.

Start with the bug and the work you need help doing:

Help me investigate this bug. Confirm the expected behavior and reproduction first, then propose a small plan before changing code. Keep the evidence, decisions, and next step with this story.

Review the proposed plan. Does it reproduce the failure? What will distinguish the competing explanations? What result will show that a correction works?

Approve the plan when you agree with it. Keep Plan approved as No until that decision has actually happened. An agreed plan should make the next action clear without pretending you already know the root cause.

4. Update the plan when evidence changes the investigation

Suppose the duplicate-row investigation produces this observation. This is an example of what a progress note might contain, not evidence collected for this article:

Observation: The inspected API response contains each result ID once,
but the UI displays an ID twice after the second refresh.
Evidence: Retain that response and the corresponding UI/state capture.
Decision: Inspect how refreshed results are combined with client state.
This response doesn't rule out every possible backend issue.
Next: Compare state before and after the refresh handler. Check whether
it appends the incoming results or replaces the previous result set.

Now the next experiment is specific. Update Current Plan to reflect that direction, and keep the observation and reasoning in Progress notes. If the evidence calls for a materially different change, review the revised plan before the agent implements it.

Keep unsuccessful attempts too. An action, its observed result, and the conclusion tell you why repeating that action may not be useful. A list of commands alone doesn't carry that reasoning.

This is where the connection to the workbench matters: the plan should reflect what you've learned while doing the job. It should help the next person, the next agent session, or you after an interruption see what to do next.

5. Close the loop in Closeout

When there's a candidate fix, verify the original reproduction and the checks agreed in the plan. Then fill the template's Closeout from actual evidence:

• Deploy evidence: identify the build and environment where the change is running. A local dogfood build can be appropriate for the trial; identify it honestly.
• Result or feedback: record whether the original failure is resolved and what the person trying the flow observed. A patch or passing check alone doesn't establish that the workflow was useful.
• Close / iterate / pivot decision: close if the evidence supports it, iterate if there's more to address, or change direction if the explanation was wrong. Leave it open if the evidence is missing.

Don't turn a proposed test or expected result into a completed observation. A story is easier to trust when it shows the boundaries of what you know.

Come back to the work with the plan still attached

When you return, open Files and read the Problem, Current Plan, and latest Progress notes before starting another change. Can you tell what you've already tried, what changed your mind, and which experiment comes next?

That's the practical lesson I'm carrying forward from my dad's bench. Keep the plan where you're working, and keep it current as you learn.

Try one story in Workbench. For this experiment, select HDD Light when creating a small reproducible bug, then open Agent → Start HDD. The linked guide covers getting started; the template and agent steps above are the HDD Light continuation.

Tell me what you could pick up without retracing your steps, and where the workflow added work. Leave private project details out of public replies.