← Patterns

Running agents
AI helps us move at lightspeed. There's no time to write everything up. So I've used my personal voice and based this on my actual work, to be able to share in real time what I'm doing with the teams I work with.

Running agents

Follow-ups that wait on an event

The steps only a person can do after a change is merged, each filed as one item, a follow-up, that waits on a fact and can be read days later without the context.

One of 15 patterns I've found working with AI coding agents. An agent drafted the words from my notes, and I haven't edited them yet. See all 15, or read how they are made.

An agent drafted the words from my notes, and I haven't edited them yet. The code was run before it went in.

The problem

Agents get a change merged quickly, but merged is not always finished. Something is often left that an agent cannot do: paste a key into a dashboard, delete the old key two days later, re-run a data sync that needs a person's own login.

The agent writes the step down wherever it happens to be: the description of the change, a comment, the last line of the chat. Then the session ends. In my experience those places are rarely reread. The step is usually not due yet anyway, and a note in any of them won't bring it back when it is.

The idea

Each step becomes one item, filed where the person already looks for open work, with a trigger: the fact it waits for, in a form a script can test. A named change, a pull request proposed for the main code, has merged, a date has arrived, someone has stated that a fact is true. When every trigger has fired, the item is ready.

The item is written for someone who was not there. A then line gives the exact step, and a proof line says how they will know it worked. Before filing, the script that files it looks for an open item that is the same step, and adds a note to it instead of filing a copy.

A version small enough to read

Four steps filed against a small set of facts. The third is a repeat of the first, worded differently.

follow-ups/tail.ts
// Steps only a person can do, each waiting on a fact. Run: bun tail.ts
type Item = { title: string; triggers: string[]; body: string; notes: string[] };
const items: Item[] = [];
// What is true now: changes merged, facts someone has asserted, and today's date.
const facts = { merged: [41, 42], asserted: ["new key live"], today: "2026-11-15" };
const fired = (t: string) => {
const [kind, value] = t.split(":");
if (kind === "merged") return facts.merged.includes(Number(value)); // keyed on the change number, not a branch
if (kind === "date") return value <= facts.today;
if (kind === "asserted") return facts.asserted.includes(value);
return false; // "manual" waits for a person to close it
};
// The first clause, lower case, is what makes two items the same step.
const key = (title: string) => title.toLowerCase().split(/[,:;]| then /)[0].trim();
function add(title: string, triggers: string[], body: string) {
const same = items.find((i) => key(i.title) === key(title));
if (same) return void same.notes.push(`filed again: ${title}`);
const missing = ["then:", "proof:"].filter((w) => !body.includes(w));
if (missing.length) console.log(`warning: "${title}" has no ${missing.join(" or ")} line`);
items.push({ title, triggers, body, notes: [] });
}
add("Paste the new API key into the payments dashboard", ["merged:41"],
"then: Settings > Keys > Replace, paste from the vault\nproof: the test charge on /admin/health goes green");
add("Delete the old API key", ["asserted:new key live", "date:2026-11-17"],
"then: Settings > Keys > old key > Delete\nproof: the key list shows one key");
add("paste the new API key into the payments dashboard, from the vault", ["merged:41"], "then: as above");
add("Re-run the customer sync", ["merged:43"], "needs your login");
for (const i of items) {
const state = i.triggers.every(fired) ? "ready" : `waiting on ${i.triggers.filter((t) => !fired(t)).join(", ")}`;
console.log(`${state.padEnd(28)} ${i.title}${i.notes.length ? ` (${i.notes.length} repeat folded in)` : ""}`);
}

Run with Bun, a JavaScript runtime, it prints:

What is ready
warning: "Re-run the customer sync" has no then: or proof: line
ready Paste the new API key into the payments dashboard (1 repeat folded in)
waiting on date:2026-11-17 Delete the old API key
waiting on merged:43 Re-run the customer sync

Where the plain form falls short

The plain form is a ticket per step, with the trigger written as a sentence. I've seen it fail in these ways.

  • A trigger in prose never fires. Nothing reads the sentence. Of 50 such tickets, 39 were still waiting when I counted.
  • Copies pile up. Several sessions notice the same step, and each files it. One step was filed three times in an evening before matching on the first clause stopped it.
  • A title is not a step. On one count, 118 of 294 open items had no body at all. The then and proof lines are what make an item usable cold.
  • A trigger keyed on a branch stops firing. A branch, the separate line of work a change is made on, is often deleted when its change is merged, so a trigger watching the branch never sees the merge. Keying on the change number fixed that.
  • Work that should end, doesn't. I once found 63 feature flags, switches that turn new code on or off, and not one had a removal date. Filing the removal item in the same change as the flag gives each one an end from the start.

Trade-offs

  • A trigger makes an item due, not done. It does not make anyone act. In under three weeks after I moved to items like these, the open list grew more than sevenfold, to 294. Each one comes back at the right time, but the list still needs clearing.
  • Matching on the first clause is crude. Two wordings of one step that differ in the first few words still file twice.
  • Some steps are not follow-ups. "Merge the change" is its own reminder. "Check it after it merges" belongs to the normal review of the change. Leaving those out keeps the list to the steps people would actually forget.

When to use it, and when not to

It suits work where agents finish faster than a person can follow up, and where the follow-up is due later than the session that noticed it. If you are the only one working and the step is due now, do it now.

Example. Follow-ups that wait on facts, on GitHub

A draft skill for this pattern

A skill is a short set of instructions you give a coding agent so it applies a pattern the way you would. Copy the text below into a file called SKILL.md, in the folder your coding agent reads skills from. In Claude Code, Anthropic's coding agent, that is .claude/skills/follow-ups/. It is a draft, and I haven't tried it on anyone else's project yet.

follow-ups/SKILL.md
---
name: follow-ups
description: Use when a change is merged or a task ends with a step only a person can do (paste a key, delete an old secret, re-run a sync that needs their login), or when adding a feature flag or starting an experiment. Files one item per step, waiting on a fact, readable days later.
---
# Follow-ups
A merged change is often not finished. The rest is a step only a person can
do, and it is usually not due yet. A line in the change description or the
last message of a chat has nothing that brings it back when it is due.
## Filing a step
1. File one item per step, where the person already looks for open work.
Mark it as waiting on a person.
2. Give it a trigger, the fact it waits for, in a form a script can test:
a change number has merged, a date has arrived, someone has stated a
named fact, or "manual". An item may need several triggers to all fire.
Key a merge trigger on the change number, not the branch name, because
branches are often deleted on merge.
3. Write the body for someone with none of your context: a `then:` line with
the exact step (command, page, button), and a `proof:` line saying how
they will know it worked.
4. Before filing, look for an open item that is the same step. If there is
one, add a note to it instead.
5. Record where the item came from without making the source wait on it. The
source can close while the follow-up stays open.
## What is not a follow-up
- "Merge the change". The open change is its own reminder.
- "Click through it after it merges". That belongs to the normal review of
the change, not a separate item.
## Work that should end
Give it its end when you start it:
- A feature flag (a switch that turns new code on or off) gets a removal
item in the same change, waiting on the change that adds it.
- An experiment gets a written hypothesis first: what you will measure, by
when, the value that means success and the value that means stop.
- "Later" becomes a condition someone can check.
## What it does not do
A trigger makes an item come due. It does not make anyone act. The list can
still grow faster than it is cleared, so count it and say so.