Workflow 020: Doc, The Agent That Fixes My Agents

I have an agent whose only job is fixing my other agents.

Once you're running a stack of named agents, each following its own process, you notice fast when one stops behaving. The trouble is noticing at all.

Doc has read access to every agent's workspace, their documentation, and their daily logs. When something breaks, or when I want to change how an agent behaves, I tell Doc. He diagnoses it and tells me what the fix is. He does not apply it himself.

That last part is on purpose.

What this replaces

Finding out an agent has been broken for three days because something downstream went quiet.

My content repurposing agent used to break constantly. It runs on an automation platform, which means it's a chain of connected steps, so one bad connection takes the whole thing down. No output, no error I'd see, no announcement.

Broken agents don't tell you they're broken. They just stop.

Blueprint

One agent diagnoses the rest.

Trigger: manual, when I notice something wrong or want a change made. Inputs: the agent registry, each agent's workspace, and their daily logs. Output: a diagnosis and a suggested fix, for me to approve.

What Doc can see:

• Every agent's documentation: who they are, what they do, what they specialise in
• Each agent's own workspace
• The daily report every agent writes at the end of its run
• The history of what each one has been doing

That daily log is the diagnostic. If an agent hasn't reported in two days, it hasn't been working for two days.

Organize

What has to exist first:

• One database holding every agent: name, purpose, specialty, where it runs
• A workspace per agent, so each has somewhere to write
• A daily reporting habit built into every agent. At the end of each run, it logs what it did and what it learned
• Read access for the diagnostic agent across all of it

Building the logging into every agent is the unglamorous part, and it's what makes this possible. An agent that never reports can't be diagnosed. Silence has to mean something.

Systematize

Doc needed to be specialised before he was useful, so part of the build was having him study the platforms my agents actually run on.

You are [AGENT NAME], my agent doctor. Your job is diagnosing and fixing
the other agents in my stack.

You have read access to:
- My agent registry: every agent, what it does, where it runs
- Each agent's workspace
- Each agent's daily logs

YOUR CORE RULE
You suggest fixes. You never apply them yourself. Diagnose, explain, and
propose. I approve before anything changes.

WHEN SOMETHING IS BROKEN
1. Read that agent's recent logs. Note when it last reported successfully.
2. Identify what failed: a connection, a permission, a changed input, a
   step that errored.
3. Tell me in plain language what broke and why.
4. Propose the fix, step by step, and tell me what I need to do to apply it.
5. Say how confident you are. If you're guessing, say so.

WHEN NOTHING IS OBVIOUSLY BROKEN
Check for silence. If an agent hasn't logged in more than [N] days, treat
that as a failure and investigate. Agents that stop working rarely
announce it.

WHEN I WANT A CHANGE
Sometimes I'll ask for new behaviour rather than a repair. Treat it the
same way: tell me what needs to change, where, and what it might affect
elsewhere in the stack.

NEVER
- Delete an agent, a workflow, or a step
- Apply a change without my approval
- Solve a problem by removing the thing causing it

How to set it up

1. Document every agent you run in one place, with what it does and where it lives.
2. Add daily logging to each agent, so there's a trail to read.
3. Build the diagnostic agent with read access across all of it.
4. Have it study the platforms your agents actually run on before you rely on it.
5. Test it on something you already know is broken, so you can check its diagnosis against reality.

Why does the platform matter?

Because different builds fail differently. Agents built as a chain of steps on an automation platform fail whole when one connection drops. Agents built as skills tend to fail partially, or produce bad output rather than none.

Knowing which kind you're diagnosing changes where you look first.

Assign

What Doc does: read logs, diagnose, explain, and propose.

What stays human: approving every change.

I want to be specific about why, because this is the guardrail I care most about in my whole stack.

An agent with permission to fix problems will eventually solve a problem by deleting the thing causing it. That's a rational move if your instruction is "make this stop failing." I've watched people give an agent that permission and lose work.

So the rule is absolute. Doc diagnoses. I approve. One easy click, but the click is mine.

Rule of thumb from this build: the agent that finds the problem never gets to delete it.

The upside I didn't plan for is that this same setup handles upgrades. When I want my inbox agent to start ignoring a category of email, that's the same job as a repair: what needs to change, where, and what else it affects. So Doc keeps the stack running, and he's also how it gets better.

Integrate

Doc sits above everything else rather than inside it:

• Every agent logs daily, which creates the trail
• When I raise a problem, Doc reads those logs and checks for silence
• When I spot bad output myself, I tell him and he investigates
• When I want new behaviour, he scopes the change and tells me what it touches
• Nothing changes until I say so

A stack of agents is a small team. Someone has to notice when one of them stops showing up.

Tomorrow: the presentation builder. Every talk I've given, in one project that outlines the next one.