DEV Community: Ricardo Morato Mateos

I built a VS Code extension to work with several agents

Ricardo Morato Mateos — Tue, 20 Oct 2026 00:00:00 +0000

Agents write the code, but I have to see it.

I need to read it, navigate it, jump to a definition, search the project and, when needed, debug it with breakpoints. An IDE already does that, and I didn't want to give it up to have agents in parallel. This post is about why I ended up building my own tool, and how I work with it.

What I tried

I tried several tools for running agents in parallel and none fully convinced me. This is what happened to me, on my machine and with my way of working:

Superset: on my machine it ate the memory.
Warp: a very good terminal, but for reading and moving around the code and the documents it fell short for me.
In general, most of them pulled me out of the editor. They give you a window with chats or terminals, and the code becomes secondary.

They are good tools. They just didn't fit the way I work: I always ended up going back to VS Code to read what the agents had written.

What I wanted

To stay in VS Code, with my navigation, my extensions, my debugger and my search, and add on top what is missing to work with several agents at once.

From the other tools, having several agents in parallel, each in its own worktree, and knowing at a glance which one needs me. From VS Code, everything else.

What Stack is

Stack is a VS Code extension, open source under the MIT license. Each task has its own git worktree, which is a working copy of the repository with its own branch, and inside it its real agent: Claude Code, Codex CLI or opencode. The agents run in tmux, so they keep working even if I reload the VS Code window.

A sidebar tells me, for each task, who is working, who needs me and what is ready for review. When an agent asks me something, its question is the line of its row. And a shortcut, Cmd+Alt+J, takes me to the task that has been waiting for me the longest.

Why inside VS Code

There are five reasons, and all five are things the editor already does.

I see and navigate the code for real. Each worktree opens as a folder in the editor. Search and Quick Open are limited to the worktree I'm in, so the work of five agents doesn't get mixed in the results.

I debug for real. Each worktree has its own debug port and its own launch.json, so I can stop at a breakpoint in one task while another keeps running. It comes set up for Node and can be changed to any debugger VS Code supports. I use it less and less, but that doesn't mean it should be left aside.

I review without leaving. There is a diff panel with per-line comments, sent straight to the agent, without going through a PR.

I run each task's environment. Each worktree can have its own docker compose, with generated ports that don't collide, and a setup script (dependencies, the .env) that runs before the agent starts.

I use the real CLIs. It's my claude or my codex, with my configuration and my subscription. It's not a reimplementation.

A normal day

I write the task in New task. Stack creates the branch and the worktree, prepares the environment and launches the agent.
While they work, I read and navigate the code in the editor. When one asks me something, I see it in its row.
I review the diff in the editor, comment and send it back to the agent.
If something doesn't add up, I debug it right there.
The latest thing, which I'm just starting to use: Stack includes an MCP server and I use the Claude Code panel as a manager. I type /stack-task with a ticket, it reads the ticket with the Jira MCP and sets up the task.

What you should know

It works on macOS and Linux. It needs tmux. On Windows, only with WSL. Native notifications are macOS only.
It's not on the VS Code Marketplace yet: you install it from the .vsix file. It's version 0.1.0.
To show live state, Stack registers a hook in each agent. In Claude Code it writes it to your ~/.claude/settings.json, and the first time it changes a configuration file it keeps the original as a copy with the .stack-backup extension.
With Codex there is a catch. Its hooks are experimental and disabled by default, and you have to enable them in its configuration. Until then, its sessions don't change state in the sidebar. Codex also asks you to trust the hooks before running them.

How I improved it

I've been improving it with agents in parallel: some reviewed the code by area, others fixed the bugs, each in its own worktree, and then came the redesign. Today it has 2,102 tests, with 100% coverage of the code it measures. The React views, which are the interface, are left out of that measurement.

Agents write the code, but I'm the one who has to understand it. That's why I stay in the editor.

The code is on GitHub, under the MIT license.

A base agent with LangGraph: tools, memory, RAG and examples

Ricardo Morato Mateos — Sun, 18 Oct 2026 00:00:00 +0000

When I start a new agent I always start from the same base. I use it every day in macro, my app for logging what I eat: I tell it what I had, or send it a photo of the plate, and it logs it with its calories and macros. I also ask it how today is going, or correct something I logged wrong.

It is JavaScript with LangGraph.js, Fastify and MongoDB. The code in this post is simplified so the idea shows, but the decisions are the ones macro has.

macro does not need RAG: everything it knows is the user's own data, and it reads it with tools. When an agent does need knowledge that is not in your database, like documentation or policies, I add RAG on top of the same base. I tell that part with what I did in aside.

What I mean by agent

A model that decides which tool to call, looks at the result and decides again, in a loop, until it has an answer. Anthropic describes it this way in Building effective agents: the basic building block is "an LLM enhanced with augmentations such as retrieval, tools, and memory", and the agent is that LLM using tools in a loop based on what the environment returns.

The same article recommends finding the simplest solution possible and only adding complexity when needed. That is why my base has two nodes and nothing else.

The graph: two nodes and a loop

One node calls the model. The other runs the tools the model asked for. If the model asks for a tool, it goes to the tools node and back to the model. If it asks for none, it ends.

import { StateGraph, START, MessagesAnnotation } from '@langchain/langgraph'
import { ToolNode, toolsCondition } from '@langchain/langgraph/prebuilt'
import { SystemMessage } from '@langchain/core/messages'

async function buildGraph({ userId, tools, systemPrompt }) {
  const model = (await getLLM()).bindTools(tools)

  async function callModel(state) {
    const response = await model.invoke([
      new SystemMessage(systemPrompt),
      ...windowForModel(state.messages),
    ])
    return { messages: [response] }
  }

  const graph = new StateGraph(MessagesAnnotation)
    .addNode('agent', callModel)
    .addNode('tools', new ToolNode(tools))
    .addEdge(START, 'agent')
    .addConditionalEdges('agent', toolsCondition)
    .addEdge('tools', 'agent')
    .compile({ checkpointer: getCheckpointer() })

  const config = { recursionLimit: 25, configurable: { thread_id: userId } }
  return { graph, config }
}

toolsCondition checks whether the model's last message has tool calls and picks the next node. recursionLimit is the brake: the maximum number of steps the graph can take in one run. LangGraph sets it to 25 by default, and I make it explicit so it is visible. If the model gets stuck in a tool loop, the run fails instead of burning tokens forever.

Tools: what the agent can do

macro has about twenty tools: log a meal, list, search, edit, delete, read the daily summary, set goals, log weight and water, look up a barcode or scan a photo.

Three decisions I repeat in any agent:

One source of tools. The same tools feed the chat and an MCP server, so other AI clients can use my data. Each tool calls an application use case, the same one the REST API uses. The chat only chooses which ones to expose.

The code sets the user, never the model. The userId is not a tool argument. It is injected from the session when the tool is created, so the model cannot ask for another user's data even if someone tries to slip that into a message.

Errors come back as data. If a tool fails, I return { error } instead of throwing. The model reads it and can correct itself: ask for the missing piece or try another id.

import { tool } from '@langchain/core/tools'

function createChatTools({ registry, userId }) {
  const ctx = { userId }
  return registry.listTools()
    .filter((t) => CHAT_TOOL_NAMES.includes(t.name))
    .map((t) => tool(
      async (args) => {
        try {
          const result = await registry.callTool(t.name, args || {}, ctx)
          return JSON.stringify(result ?? null)
        } catch (err) {
          return JSON.stringify({ error: err.message || 'tool failed' })
        }
      },
      { name: t.name, description: t.description, schema: t.inputSchema },
    ))
}

Each tool's description matters as much as its code. It is all the model knows about it. Anthropic calls it the agent-computer interface, and recommends putting as much care into it as into an interface for people, with usage examples and edge cases. Which brings me to examples.

Examples in the prompt (few-shot)

Few-shot means giving the model a few examples of what you want inside the prompt itself, without retraining it. The name comes from Language Models are Few-Shot Learners, the GPT-3 paper. Today it is one of the cheapest tools you have: Claude's prompting guide says examples are one of the most reliable ways to steer format, tone and structure, and recommends 3 to 5, close to the real use case, varied and kept apart from the instructions.

I use them in three places.

In each tool's description, with real phrases. I do not write "searches the meal history", I write the phrases people actually say. macro's users write in Spanish, so the examples are in Spanish:

search_meals: search the user's meal history by name and macro/date filters.
Use for "¿qué cenas con más proteína comí esta semana?", "busca tortilla",
"desayunos de más de 400 kcal de los últimos 14 días".
Prefer this over list_meals when the user is looking for specific meals.

With that, the model does not have to guess when to use search_meals and when list_meals.

In the rules, as sequences. Corrections are what breaks most if you do not spell them out. So the prompt says what to do with "it was yesterday", "make it 600 kcal" or "move it to dinner": first list_meals for the right day, then update_meal on the right id. It is an example of what to do, not only of what to say.

For tone, a written conversation. In aside I do not describe the tone with adjectives. I describe a support person and write sample sentences of theirs: how they greet, how they ask for a detail, how they say something cannot be done. Every model reads an adjective like "friendly" its own way. A written sentence, it does not.

If what you need is an exact output format, you can also put the examples as user and assistant message pairs before the conversation. In an agent with tools I prefer to keep them in the system prompt, because they do not mix with the real history.

The prompt: scope, rules and the date

macro's system prompt has four parts:

Scope. It only helps with the user's diet. If asked something else, it deflects in one sentence and offers something useful, without explaining why it will not answer.
The tools and when to use each one , with the examples above.
Rules. Read the daily summary before answering how today is going, never save a photo result without confirming, answer in one or two sentences after a tool, never moralize.
The date. Computed on every message.

The date looks trivial and it is not. The model does not know what day it is, and "yesterday" or "on Monday" have to be resolved. So the prompt carries today, yesterday and tomorrow already computed, plus the rule to use the current year when the user does not say one.

function buildSystemPrompt({ now = new Date() } = {}) {
  const today = now.toISOString().slice(0, 10)
  return `${SYSTEM_PROMPT}

Current date: ${today} (UTC).
- If the user does not mention a date, use ${today}.
- "ayer" / "yesterday" is ${shiftDate(today, -1)}.
- A day and month without a year use the current year.
Never invent a past or future year.`
}

I also pass a precomputed summary of the day: what was consumed, the target and what is left. With the instruction to use the tools for exact answers and the summary only as backup.

The last rule in the prompt treats any user message or image as data, never as instructions. A rule in the prompt is not a guarantee, but it helps. The real guarantee lives in the code: the injected userId and the confirmation before deleting.

Memory: the thread in Mongo and a short window

LangGraph keeps the conversation memory with a checkpointer. According to its persistence docs, the checkpointer saves the graph state per thread, and the thread is picked with a thread_id in the config. I use the MongoDB checkpointer with the app's own connection and the userId as thread_id: one conversation per user, which survives reloads and moves across devices for free.

import { MongoDBSaver } from '@langchain/langgraph-checkpoint-mongodb'

const checkpointer = new MongoDBSaver({
  client: mongoose.connection.getClient(),
  dbName: mongoose.connection.db.databaseName,
})

Saving everything does not mean sending everything to the model. Each message only carries the last 10, so the cost does not grow with the conversation. The full history stays in Mongo and the UI loads it from there.

There is a catch when cutting. Every tool result has to come after the call that asked for it. OpenAI's API requires each result to reference its call by id. If the window starts right on a tool result, its call was left out and the request fails. So the window never starts on one:

const MAX_CONTEXT_MESSAGES = 10

function windowForModel(messages, max = MAX_CONTEXT_MESSAGES) {
  if (messages.length <= max) return messages
  let start = messages.length - max
  while (start < messages.length && messages[start].getType() === 'tool') start++
  return messages.slice(start)
}

RAG: when the agent needs to know things

RAG is retrieving relevant text and giving it to the model so it answers with it. The term comes from this 2020 paper. What matters is where that text comes from.

In macro, what the agent needs to know is the user's meals. That is structured data, so retrieval is search_meals, a Mongo query with filters on name, date and macros. You do not need embeddings to find "breakfasts over 400 kcal".

In aside it was needed: the agent answers with each customer's documentation. I set it up the same way, as one more tool:

const searchDocs = tool(
  async ({ query }) => {
    const hits = await searchKbDocuments(workspaceId, query)
    return JSON.stringify({
      results: hits.map((h) => ({ title: h.title, text: h.excerpt.slice(0, 600), url: h.source })),
    })
  },
  {
    name: 'search_kb',
    description: "Search the knowledge base for articles relevant to the user's question. "
      + 'Use when the user asks something that might be documented.',
    schema: z.object({ query: z.string().describe('Concise search query') }),
  },
)

As a tool, the model decides when to search and with which words, and can search twice if the first try is not enough. I return it trimmed and with its source, so the UI can show the source under the answer.

My rule of thumb:

Few documents: search by terms, which is what I use in aside.
Many documents, or users who ask with different words than the docs use: embeddings.

And what comes out of the search is external content. OWASP calls it indirect injection: instructions that arrive inside a website or a document. It is treated as data, just like the user's message.

Before deleting, ask

delete_meal does not delete. It returns a pending confirmation with the id, and the UI shows a button. The real delete is done by the REST API when the user presses it.

if (t.name === 'delete_meal') {
  return JSON.stringify({ pendingConfirmation: true, action: 'delete', id: args?.id ?? null })
}

The prompt tells the model to call the tool once and say that the user has to confirm with the button. OWASP recommends the same for any risky action: a person approves it. Photos work in a similar way: the agent shows what it detected and saves nothing until the user confirms or corrects it.

For payments or emails, which cannot be undone, you also need idempotency. I covered it when writing about duplicated webhooks.

Streaming

To show the answer while it is written I use streamMode: 'messages'. The streaming docs explain that each chunk comes with metadata, including the node that produced it. I filter by the agent node so tool output does not leak into the chat:

const stream = await graph.stream({ messages: [userMessage] }, { ...config, streamMode: 'messages' })

for await (const [chunk, metadata] of stream) {
  if (metadata?.langgraph_node !== 'agent') continue
  const text = extractText(chunk.content)
  if (text) yield { type: 'token', content: text }
}

When it ends I read the thread state and check which write tools ran in this turn. That way the UI knows whether to refresh the daily counter or show the confirm button, without parsing the model's text.

Voice: listening and talking

aside used to have voice. I removed it because it caused problems, it was expensive and it was not the core. But it worked, and adding it on top of this base is easier than it looks, because the agent does not notice: voice comes in as text and goes out as text.

Listening (STT). I used ElevenLabs' Scribe v2 Realtime from the browser, with their React hook. The browser asks my server for a token, so the API key never leaves the server. The mic is turned into 16 kHz audio and sent over a WebSocket. Scribe detects when you stop talking (about 0.8 seconds of silence) and returns the whole sentence. That sentence enters the graph as one more user message.

What fought back the most was echo. The mic stays open while the agent talks, so you can interrupt it, and it hears the agent itself. So while it talks I drop sentences under four words, and also loose noise of one or two words.

Talking (TTS). ElevenLabs Flash v2.5, also over a WebSocket. I do not wait for the model to finish: I pass the text to ElevenLabs as it arrives through the stream, and it starts talking with the first sentence. On this base it would look like this:

const speaker = await tts.startTurn(audioSink)

for await (const [chunk, metadata] of stream) {
  if (metadata?.langgraph_node !== 'agent') continue
  const text = extractText(chunk.content)
  if (!text) continue
  yield { type: 'token', content: text }
  speaker.feedDelta(stripMarkdown(text))
}

await speaker.end()

Three details made it usable:

One socket per turn. If each sentence goes on its own, each one sounds like it starts from scratch. With one socket per answer, the intonation carries from one sentence to the next.
Strip the markdown before speaking. Otherwise it reads the asterisks and hashes out loud.
A cache per sentence. I store each sentence's audio in Mongo. The ones that repeat, like the welcome line, come from there without paying again.

And if the user talks over it, the audio stops and a new turn starts.

Switching models without touching the agent

The agent does not know which model it uses. getLLM() builds the client from a setting stored in the database: OpenAI by default, Gemini, or MiniMax through its Anthropic-compatible API. The setting is cached for five seconds, so I switch provider from the admin panel without deploying.

That is what lets me try a new model on my real data in a minute. If the new model misuses a tool, I almost always fix it in the tool's description or in an example, not in the graph.

What I leave out at the start

No multiple agents, no planners, no long-term memory, no embeddings up front. The two-node loop, well-described tools, examples with real phrases, the thread in Mongo with a short window, and a confirmation before anything that cannot be undone. With that, macro works every day, and I add the rest when a real case asks for it.

None of this may be the best way. It came out of trial and error, and it is what works for me.

Planning with AI: make it ask before it proposes

Ricardo Morato Mateos — Fri, 16 Oct 2026 00:00:00 +0000

I have a skill for planning features with AI: rstack-plan, one of the skills in rstack. I use it when I describe something I want to build, not a bug. For bugs I have another one.

It does one thing: it listens, checks what already exists and negotiates the plan with me, question by question, before touching code.

The rule

The skill starts with a sentence: don't act on assumption, propose or listen, never just do.

It came from something that happened to me. I asked the AI to think through a new skill together and, instead, it handed me a finished diagram, with its own design, without having first confirmed that it had understood what I wanted. The solution wasn't asking it to think harder. It was a structure that makes jumping ahead impossible.

Its job ends in an approved plan, saved in the repository. It doesn't write implementation code: whatever happens after approval is separate work.

And Claude Code's plan mode

Claude Code already has a plan mode: according to its documentation, Claude reads files and proposes a plan, but makes no edits until you approve. It works for not touching the disk.

What I'm after is something else. A plan that arrives whole, all at once, is a decision made alone with an approval request attached. I want the plan to be built with my answers.

The four phases

Each phase ends with a stop: the skill tells me what it has done and waits for my answer before continuing.

The first is listening. It restates my request in its own words, without adding scope. It doesn't search the code or touch anything yet. If the request is ambiguous, it says what is ambiguous instead of resolving it by guessing the obvious interpretation. And it waits for explicit confirmation. A "yes" counts. A correction is not a soft adjustment: it goes back to phase 1 and restates from scratch. There is no exception for size: a request that looks simple goes through the same gate.

The second is looking at what already exists, read-only. The question isn't how something similar is done here, in the abstract. It's whether something that already exists can be used as is, instead of building something new. For each piece it finds, it says whether it can be reused as is, with changes or not at all, and why. The example the skill gives: if I ask for a new kind of plugin, the right output of this phase is "there is already a working OAuth flow for plugin authentication, reuse it", not a generic review of authentication patterns. This is where the first file is written, specs/<feature>/spec.md, with the what and the why, never the how.

The third is proposing, by negotiation. It doesn't hand me a complete plan. It asks me questions one at a time about what the previous phase left open, and the plan is built with my answers. Each question has to be answerable in a single message: it doesn't pack three decisions into one because it's faster. The plan.md file grows with the conversation: after each answer, the relevant section is updated, not at the end. A file that is only written at the end is the chat transcript with extra steps.

If the feature has a flow or several actors, the skill draws a diagram and keeps updating it as I decide each piece. For that it uses archify if it's available. If it isn't, it says so and carries on with text only: it doesn't fake a diagram in ASCII.

The fourth is the approval gate. There are only two valid answers: "this plan is enough", and then spec.md and plan.md are the deliverable and nothing gets implemented; or "yes, implement it", and the skill ends, because implementation is separate work. A "sure", a thumbs up or changing the subject is neither, and it asks again. When the gate closes, it gives me the file paths and doesn't commit them to git: that's up to me.

The red flags

These are the signs that force a stop:

Writing the whole plan before asking a single question.
Drawing a diagram "to show progress" before I have decided that piece.
Treating an "ok", or silence, as approval.
Looking for existing code after proposing a new design instead of before. If reuse doesn't come first, it never gets considered.
Skipping a phase because the request "seems simple".
Keeping the decisions in its head and writing spec.md and plan.md all at once at the end.

Which files it writes

Only three kinds: spec.md, plan.md and the drafts of their diagrams. It never touches the application's code.

It also doesn't create by default the rest of the files from the spec-kit convention, GitHub's toolkit for spec-driven development: data-model.md, contracts/, research.md or tasks.md. It adds one only if that feature needs it, and says why.

What it costs

It asks more questions and is slower than a plan delivered all at once. That's on purpose. And it isn't for everything: it's meant for features that aren't trivial, not for a bug. A configuration value or a single field doesn't get a diagram, although it does go through the first gate.

For something new, make it ask before it proposes.

A hard harness for fixing bugs with AI

Ricardo Morato Mateos — Fri, 16 Oct 2026 00:00:00 +0000

I've lived through the progression of AI from the start: copying code challenges into ChatGPT, then Gemini, then Claude, and now everything agentic, with its harnesses and its tools.

AI is getting more and more independent. For my personal projects it works well. Starting something from scratch or putting out a new website, inside a small codebase without much shared domain, isn't bad. The problem shows up in day-to-day work: the ticket, the task, the fix, the bug.

What happened to me

Since Opus 5.5 came out, my impression is that it does worse at that work. I'm not saying it as a fact: it's what I've seen, in my workflow.

It gets too clever when creating tasks and sets aside the harness I had built. Before, with TDD, I would check whether the tests were written and what they implied, and then we would look for the bug. That harness was going quite well for me until recently. In the last ten bugs I've shipped, I've had to guide it step by step myself, because the solutions it gave me weren't correct.

It's not that I would have done it better or worse. It's that I had the knowledge to know that wasn't what had to be done.

There's a second thing I don't fully understand: it finds more and more things risky. Querying some logs or running a query against a database that isn't production, something it used to do without any problem, now seems dangerous to it. For now I do it by hand and that's it.

And a third, deeper one: they sell you that AI can do everything, that it fixes everything and ships everything. In my work, no.

The answer: a hard harness

My harness is no longer a soft one, made of suggestions. It's a hard one, where the AI has to follow strict steps and can't step outside them.

I've published it as rstack. They are Claude Code skills: according to the documentation, a skill is a SKILL.md file with instructions that Claude loads when needed, or that you invoke yourself. My skills aren't advice, they are sentences of the kind "don't do X until Y". They were born in the same spirit as gstack, with one design difference: each skill stands on its own, with no shared document that all of them point to.

The one this post is about is rstack-investigate, the one for bugs. The repository also has others for planning features, reviewing PRs and doing QA in the browser.

The rule that isn't negotiable

The skill starts with a rule: no root cause is proposed and no fix is written without having reproduced the bug with real data. Reading the code and reasoning about what should happen is not proof.

It came from something that happened to me twice in the same session with the AI: it proposed a cause without checking the account's real data, and then it built an entire fix by reading code, which was useless in production because the data it depended on didn't exist. Both times I had to stop it myself.

The seven phases

The cycle has seven phases, and at the end of each one the skill stops, tells me what it found and asks me before continuing. It doesn't run on its own from start to finish.

The first is reproduce. It reads the symptom as it arrives, without reinterpreting it, traces the code backwards and looks at the git history in case it's a regression. Then it reproduces the bug with real data, as an automated test inside the repo itself, and watches it fail. It doesn't first write a loose script "to understand": if the project has tests, the reproduction is that test. If a piece of data is missing, it asks for it, it doesn't make it up.

The second compares with bugs already fixed and rules out the typical patterns: a race condition, a null that propagates, a half-finished state, a failing external integration, configuration that differs between environments, a stale cache. A bug that comes back to the same place is a sign of architecture, not a coincidence.

The third tests the hypothesis. It adds temporary logs right at the suspected point, runs the same test and reads the output line by line. If three hypotheses fail in a row, it stops and asks me, because it may be an architecture problem and not a wrong hypothesis. Before fixing anything, it removes all the logs.

The fourth is the fix. The fifth reproduces the original bug again and delivers a report. The sixth checks what looks like the bug, without dismissing it or covering it by ear: if it doesn't apply, it says why.

The seventh is the audit. A clean subagent, with no context at all, reads all the project's ADRs (architecture decision records) and all my principles documents, the knowledge/ folder, and checks the solution against each one. Not against the ones that sound relevant: against all of them, with an N-of-N count so it's visible that none was skipped.

The red flags

In the third phase there is a list of signs that force a stop:

"A quick fix for now". There is no "for now": you fix it properly or you escalate.
Proposing a fix before having traced the complete flow of the data. That's guessing.
Trusting a subagent's reading of the code, or your own, without checking it against the real case. A piece that fits "in theory" can depend on data that doesn't exist in production.
Doing a find and replace over a shared file to isolate an experiment, without scoping it to your block. After any bulk edit, you look at git diff --stat: if it touches more lines than expected, you revert it and redo it scoped.
Wanting to delete or consolidate shared code as a first idea, without having checked who else calls it. It's an assumption dressed up as elegance.

The fix: the least dangerous, not the cleverest

When there is more than one way to fix it, the skill prefers the one that can break the least if I'm wrong. In this order:

A localized fix, scoped right where the bug lives, with its test. It's the default when I don't know who depends on the shared code next to it.
A new, small, isolated piece, if the localized fix would force me to dig into logic I don't fully understand. It's more code, but it can't break what I haven't looked at.
Touching the shared code (consolidating, deleting or adding a guard) only after having checked every place that calls it. It's the strongest fix, because it makes that kind of bug impossible, but if I miss a caller, I break more than I fix.

The regression test is the same one from the first phase, the one that was already failing with real data. You don't write a new one: you apply the fix and check that this one goes green, and then the whole suite. And if the fix touches more than five files, the skill asks me before continuing, because that's too much for a bug.

Why an integration test

I work with e-commerce flows and, in that kind of system, a bug rarely lives in a single place. It depends on several contexts at once: contacts, taxes, invoicing.

Each piece on its own is usually fine. Even so the bug exists. That's why an isolated test doesn't work for me: I need an integration test that replicates the whole path. The skill prefers it to a unit test with mocks, because a test that fakes exactly the dependency where the bug lives can make a wrong fix look correct. It's an old debate, classical style versus mockist style, which Fowler sums up in Mocks Aren't Stubs.

The report

The fifth phase ends with a report shaped like this:

Symptom: [what the user reported]
Root cause: [what was actually wrong, confirmed with evidence]
Fix: [what changed, with file:line]
Evidence: [test/reproduction output before and after]
Regression test: [file:line]
Status: DONE | DONE_WITH_CONCERNS | BLOCKED

The skill won't let me say "this should fix it". It proves it with the test and with the original reproduction. And if the test used real production data, it says so, without passing it off as synthetic.

When I don't use it

It isn't for a typo or a one-line fix that I've already diagnosed myself. And it's slow by design: seven phases with a question each. That's the price of not letting anything get skipped.

To start something from scratch, AI on its own is still fine. For a bug, this.

Why I rewrote aside

Ricardo Morato Mateos — Sun, 04 Oct 2026 00:00:00 +0000

I've rebuilt aside more than once, and the last rewrite is the one that changed the most. Before I say what I changed, the first thing: I tried to sell aside and I couldn't. I'm not saying it with drama, it's what happened.

What I tried first

Between March and May I was posting about aside on LinkedIn. I saw no results and I stopped.

How it was before

The first version "saw" the screen and decided on the spot where to click or what to highlight. It failed too much. When something fails because of how it's set up, tuning doesn't fix it.

What changed

Now it's your app that tells aside what it can do: create an invoice, change a setting, open a screen. aside chooses what to do and with what data, and your own code runs it.

You tell it "invoice Orbit Labs €2,400 for the month of September" and it leaves the invoice filled in, ready for you to send. What changes is who decides what is possible: your app, not aside guessing.

What I removed

Before, you could also talk to it by voice. I realised it caused problems, it was very expensive and it wasn't essential. I removed it to focus on making what it does work well every time.

The price

Before, it started at €249, too much for solo founders and small startups. Now it starts at €49.

Before and now

	Before	Now
How it decides what to do	It saw the screen and decided where to click	The app tells it what it can do, aside picks and the SaaS's own code runs it
Voice	You could talk to it	I removed it
Price	From €249	From €49

What it does today

Two things. The first is onboarding: it takes your users through setup step by step, in a guided and natural way, and fills in each field while they talk. The second is support: it answers with your documentation and, when that isn't enough, it acts.

aside's own dashboard runs on aside: you tell it in one sentence how you want your agent and it sets it up for you.

All of this came from talking to customers and seeing where it failed. I don't know if it's the final version, but it is the most polished one.

So far, three conversations

I've talked to three leads. That's few, and I'm not going to draw market conclusions from three people. What I'm telling you is what happened.

One told me the price was expensive. The other two never replied.

About the one who said it was expensive I know something concrete: for that person, the price is an objection. It's a data point, even if it's only one.

About the two who disappeared I know nothing. A silence is not a no, and it's not a yes either. It doesn't tell me whether they weren't interested in the product, whether the timing was bad or whether my message didn't manage to say anything to them.

With three conversations there is no pattern yet.

Why your webhooks arrive duplicated and how to stop them costing an invoice

Ricardo Morato Mateos — Sun, 27 Sep 2026 00:00:00 +0000

In an ERP, a duplicated webhook is not a technical bug. It's a wrongly issued invoice.

I work on the ecommerce integrations of a SaaS ERP: Shopify, WooCommerce, PrestaShop. Each store sends us events about its orders, and the expensive mistake is always the same: the system does the same thing twice, or does today what was already corrected yesterday. In this post I explain the layers I use to avoid it and why each one exists.

What you can't assume about a webhook

A webhook does not guarantee that an event arrives only once or in order. Shopify, for example, does not guarantee ordering within a topic or across topics for the same resource and recommends ignoring duplicates with the X-Shopify-Webhook-Id header.

With one store it's rare. With thousands of integrations, rare stops being rare: any combination of duplicate, concurrency and disorder happens every day. That's why there is no single solution. There are layers, and each one covers a gap the others don't see.

Before the layers there is a base rule: the endpoint only verifies the signature, stores the event exactly as it arrives and responds 200. Everything else happens in a worker, so the response does not depend on how long processing takes. Storing the raw event also lets you reprocess and audit it when there is a bug.

And a webhook is a notification, not the truth. For a critical decision, like issuing an invoice, it's better to request the order again from the store's API instead of trusting the payload you received.

Layer 1: discard the identical before processing it

The cheapest one. You compute a hash of the payload and store it in Redis with an expiry. If it already exists, the event is a repeat and you discard it without touching the database.

// Illustrative example, not the real code
$key = "webhook:{$shopDomain}:" . hash('sha256', $payload);

// SET NX EX: check and mark in a single atomic operation
if (!$redis->set($key, '1', ['NX', 'EX' => 300])) {
    return; // already received, discard
}

try {
    $this->inbox->store($rawEvent); // durable, unique per event id
} catch (\Throwable $e) {
    $redis->del($key); // if it wasn't stored, the provider's retry must be able to get through
    throw $e;
}

What matters is that checking and marking is a single operation, which is exactly what SET with NX and EX does. If you do a GET and then a SET, two copies of the same event that arrive at the same time both get through. The key includes the store because the same id can repeat across different stores.

Even so, this layer is an optimisation: Redis can lose or expire the key, so the deduplication that guarantees anything is the durable one, with a unique constraint on the event id. What Redis does do is take work off your plate: in my case it discards about a quarter of the events before they use up resources.

Layer 2: a lock per order

The hash doesn't help against two different events for the same order that arrive almost at once. If two workers process them in parallel, each one reads the order's state, modifies it and writes it, and the last one to write wins.

The solution is to serialise the work per order with a distributed lock: before processing, the worker takes that order's lock and, if another worker holds it, it retries a bounded number of times, with some randomness in the wait, or puts the event back on the queue. But the lock coordinates, it doesn't prove correctness. What really prevents losing a write is saving with a conditional write by version, which fails if someone got there first.

// Illustrative example, not the real code
$lockKey = "lock:{$tenantId}:order:{$orderId}";
$token = bin2hex(random_bytes(16)); // unique per acquisition

if (!$redis->set($lockKey, $token, ['NX', 'PX' => 30000])) {
    throw new RetryLater(); // another worker is on this order
}

try {
    $this->process($event); // the final save is a conditional write by version
} finally {
    // Lua script: if get(key) == token then del(key); never GET and then DEL
    $redis->eval(self::RELEASE_IF_OWNER, [$lockKey, $token], 1);
}

Three details that matter: the lock expires (it's a lease, with a duration longer than the measured time the work takes), the value is a unique token per acquisition and it's released by comparing that token atomically. Even so, if the worker takes longer than the lease, another one gets in while the first is still writing. That's why the lock doesn't replace the conditional write or business idempotency.

Layer 3: ignore what arrives late

Even if they don't overwrite each other, events can arrive out of order. An ordering guard compares the event's date with the date of the last state you have already applied, discards the one that is older and records that it discarded it.

// Illustrative example, not the real code
// The watermark lives in the order itself
if ($event->emittedAt() < $order->lastEmittedAt()) {
    $this->logger->info('webhook.stale_discarded', ['orderId' => $orderId]);
    return; // older than what has already been applied
}
// when saving, the same check goes inside the conditional write

You have to decide what you compare. The event's date at the provider, not the time it reached you, because delivery can be delayed. If the provider also gives a version or a sortable id, store it: two updates in the same second tie on date. And the check must travel in the conditional write, not only in a previous if, because between the if and the save another worker may have got ahead.

Layer 4: what a hash can't see

The same refund can arrive by two different routes, with different payloads. To the hash they are two unrelated events, so both get through.

Here I don't deduplicate messages, I apply business idempotency: the key comes from the identity of the refund (the store and the refund id), not from the content or the delivery. The question changes from "have I seen this message?" to "have I already applied this refund?". That key has to live in the database with a unique constraint and store the result, so a retry returns the same thing. In Redis, which expires, it's not enough.

Don't overwrite what the merchant edited by hand

A merchant can edit a document by hand after we have generated it. If another sync event arrives, you don't want to overwrite that edit.

For that I compare two hashes: one of the fiscal fields and one of the non-fiscal fields. That way I see what has really changed between what I have and what arrives, and I don't flatten a manual edit. So that the hash doesn't invent differences, you have to normalise the amounts to the same precision and sort the keys before computing it.

The exchange rate, fixed to the original document

A detail that causes false differences: if an order is in another currency and you recalculate with the exchange rate of each event, the volatility between one event and the next makes the amounts not add up even though nothing has changed.

I fix the exchange rate of the original document across the whole chain of events, so the amount only changes when the order changes.

Summary of the layers

Layer	What it prevents	Where the guarantee is
1. Hash in Redis	Processing an identical event twice	In durable deduplication by event id: Redis only saves work
2. Lock per order	Two workers processing the same order at once	In the conditional write by version
3. Ordering guard	An old event overwriting a new one	In the check inside the conditional write
4. Business idempotency	Applying the same refund twice	In a durable key with a unique constraint

What's left

None of these pieces is sophisticated on its own. What's hard is having all of them, and having every new incident come in with a test that stops it from happening again; how I automate that cycle is in From a Slack thread to a pull request. With the four layers and those two precautions, a repeated or out-of-order event should not change the order twice.

And since webhooks also get lost, the system has to converge even if none arrives: that takes a periodic reconciliation against the store, which Shopify also recommends.

From timeout to 10 seconds: finding the real bottleneck

Ricardo Morato Mateos — Sun, 20 Sep 2026 00:00:00 +0000

There was a screen that, on large accounts, would not open.

It was the listing of document items. On accounts with a lot of volume it hit the nginx timeout, 60 seconds, and for the customer it was simply unreachable. That module was already built. I rebuilt it on my own, frontend and backend.

The backend is PHP with Symfony and CQRS, and the frontend is React. I simplify the code in this post so the idea is clear.

Measure before touching

The temptation is to optimise the first thing that smells bad. Before that, I looked at where the time and the memory were going, and not only the total time: a high total time doesn't tell you whether the problem is the database, the ORM or the frontend. The bottleneck was the ORM's memory consumption.

When an ORM loads many records, it turns each one into objects, and those objects take up memory for as long as they stay alive. With tens of thousands of products, that memory shoots up and the listing never finishes in time.

First change: process in batches

Instead of loading all the items at once, I process them in batches and free memory between one and the next. This is the pattern in the Doctrine batch processing documentation, which calls clear() between batches to free memory.

foreach (array_chunk($ids, $batchSize) as $chunk) {
    $items = $repository->findByIds($chunk);

    yield from $this->present($items);

    $entityManager->clear(); // releases the objects from the previous batch
}

This step still hydrates full entities, but memory stops growing with the size of the account and depends mostly on the size of the batch. That size is a trade-off: bigger performs better, smaller uses less memory, and you choose it by measuring.

Second change: a view instead of the aggregate

Even when processing in batches, loading the full aggregate of each item is expensive. The aggregate exists to protect invariants when writing, and to render a list you don't need it. So I applied a view: the listing no longer goes through the aggregate and reads a read projection, a flat object with only the fields the screen renders.

In CQRS that is a query with its handler, and the handler loads nothing: it asks a read gateway for the data.

final readonly class ListDocumentItemsQuery
{
    public function __construct(
        public string $tenantId,
        public string $documentId,
    ) {}
}

final readonly class ListDocumentItemsQueryHandler
{
    public function __construct(private DocumentItemsReadGateway $items) {}

    /** @return iterable<DocumentItemView> */
    public function __invoke(ListDocumentItemsQuery $query): iterable
    {
        yield from $this->items->stream($query->tenantId, $query->documentId);
    }
}

The handler returns an iterable, not an array. That is the key to everything that comes next: with a generator, only one row is in memory at a time, the one being processed.

The read gateway is the one that talks to the database. It projects only the fields that are needed, sorts in a stable way and hands out rows with yield as the cursor brings them:

final class MongoDocumentItemsReadGateway implements DocumentItemsReadGateway
{
    /** @return \Generator<DocumentItemView> */
    public function stream(string $tenantId, string $documentId): \Generator
    {
        $cursor = $this->collection->find(
            ['tenantId' => $tenantId, 'documentId' => $documentId],
            [
                'projection' => ['sku' => 1, 'name' => 1, 'quantity' => 1, 'price' => 1],
                'sort' => ['_id' => 1], // stable order, with a unique tie-breaker
                'batchSize' => $this->batchSize,
            ],
        );

        foreach ($cursor as $row) {
            yield DocumentItemView::fromRow($row);
        }
    }
}

The heavy fields, the ones only needed on small accounts or when opening the detail, are loaded conditionally depending on the size of the account. Separating reads and writes this way doesn't require a second database or event sourcing: the separation is logical.

Third change: streaming from the controller

With an iterable in hand, the controller can start responding without waiting to have all the rows. In Symfony this is done with a StreamedResponse that writes one line of JSON per item (NDJSON) and flushes:

#[Route('/documents/{documentId}/items', methods: ['GET'])]
final class ListDocumentItemsController
{
    public function __construct(private QueryBus $queryBus) {}

    public function __invoke(string $documentId, TenantContext $tenant): StreamedResponse
    {
        $items = $this->queryBus->ask(
            new ListDocumentItemsQuery($tenant->id(), $documentId),
        );

        $response = new StreamedResponse(function () use ($items): void {
            foreach ($items as $i => $item) {
                echo json_encode($item, JSON_THROW_ON_ERROR) . "\n"; // one row per line

                if ($i % 100 === 0) {
                    flush(); // sent in batches, not row by row
                }

                if (connection_aborted()) {
                    return; // the client has gone, we stop reading
                }
            }
        });

        $response->headers->set('Content-Type', 'application/x-ndjson');
        $response->headers->set('X-Accel-Buffering', 'no'); // nginx must not buffer the response

        return $response;
    }
}

Two details matter. The first, X-Accel-Buffering: no: without it, nginx buffers the response and the client receives nothing until it finishes, and the streaming is pointless. The second, that nginx's read timeout is measured between two reads, not over the whole response: as long as rows keep arriving, it doesn't trigger. Symfony also ships StreamedJsonResponse, which accepts generators; here I use NDJSON because the frontend reads the stream line by line.

Fourth change: React renders with the first results

The other side is making the frontend not wait. To read the stream, an async generator that splits the lines as they arrive:

async function* streamItems(documentId: string, signal: AbortSignal) {
  // In the real frontend this sits behind a repository, with the whole DDD layer; here it goes straight to fetch to keep it simple
  const response = await fetch(`/api/documents/${documentId}/items`, { signal });
  if (!response.ok || !response.body) throw new Error(`HTTP ${response.status}`);

  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += value;
    const lines = buffer.split('\n');
    buffer = lines.pop() ?? ''; // the last line may arrive half-finished

    for (const line of lines) {
      if (line) yield JSON.parse(line) as DocumentItem;
    }
  }
}

And to hook it up to useQuery, TanStack Query's streamedQuery: it accumulates the chunks that arrive into an array. The query is pending until the first one arrives, moves to success at that moment, and stays fetching until the stream closes.

import { queryOptions, useQuery, experimental_streamedQuery as streamedQuery } from '@tanstack/react-query';

const documentItemsQuery = (documentId: string) =>
  queryOptions({
    queryKey: ['document-items', documentId],
    queryFn: streamedQuery({
      streamFn: ({ signal }) => streamItems(documentId, signal),
    }),
  });

function DocumentItemsList({ documentId }: { documentId: string }) {
  const { data = [], isPending, isFetching } = useQuery(documentItemsQuery(documentId));

  if (isPending) return <ListSkeleton />;

  return (
    <>
      <ItemsTable rows={data} />
      {isFetching && <p>Loading more…</p>}
    </>
  );
}

streamedQuery is still marked as experimental in TanStack Query, so its API may change.

For the person using the screen, the difference is huge: they see the first item almost immediately, instead of having to wait 40 seconds to see it.

What to watch out for with streaming

While rows are arriving the total isn't known yet, so the screen shouldn't show an "of N" or an invented percentage. The order has to be stable, with a unique tie-breaker, or a row can appear twice or be skipped. And it's better to send the rows in batches, not one by one, because with tens of thousands of rows rendering each one separately eats the browser.

Summary of the changes

Change	What it removes
Batches	Memory growing with the size of the account
A view instead of the aggregate	Hydrating the full aggregate of every item
Streaming from the controller	Waiting for all the rows before responding
React with `streamedQuery`	Waiting for everything to arrive before rendering

Result

From timeout to about 10 seconds, with the screen filling up from the first results. With that you can get into accounts with more than 100,000 products.

Ten seconds is not fast, but before it didn't open.

The same thing, at another scale

In the webhook pipeline, which I cover in Why your webhooks arrive duplicated, I follow the same rule. I use Datadog's APM and traces to see which parts of the flow are really slow, and I aim the optimisation there, not where it seems. The traces are sampled and are useful for performance; it's also worth measuring how long each message waits in the queue, because sometimes the slow part is the wait and not the code.

Before optimising, measure.

From a Slack thread to a pull request: an agent that reproduces the incident

Ricardo Morato Mateos — Sun, 13 Sep 2026 00:00:00 +0000

A customer incident usually starts with a support message in Slack: this store had this happen with an order. And from there the path is almost always the same.

The manual path

Find the pipeline logs, reconstruct which webhooks arrived and in what order, understand what happened, write a test that reproduces it and, finally, fix it. Almost all of it is mechanical, and the only thing that changes from one incident to the next is the case. That's why I built an agent that walks that path.

What the agent does

Starting from the Slack thread:

It retrieves the pipeline logs.
It reconstructs the real sequence of webhooks we received from the store.
It generates a test that reproduces the case.
It proposes the fix in a pull request.

When reconstructing the sequence you have to look at two clocks: the order in which each webhook arrived and the date on which the provider emitted it. Many incidents are exactly the difference between the two; I cover the layers I use to prevent them in Why your webhooks arrive duplicated.

First the test, then the fix

The order matters. In my area, every incident comes in with a test that stops it from happening again, so the agent doesn't start by fixing: it starts by reproducing.

A test that fails for the right reason is the proof that you have reproduced the problem, and reproducing it is the first step to understanding it. If the agent can't reproduce the case, there is nothing to fix yet. Sometimes the cause is that a piece of data is missing: a webhook that never arrived or an external result that was left in doubt. That is also a useful result, and it's better to know it before it proposes a blind patch.

For a webhook incident, the test has to be deterministic: the events in the order in which they happened, a fixed clock and fakes that respect the same constraints as production, like uniqueness and versions, because a fake without them makes a concurrency test lie. The payloads come from real cases, but they have to be scrubbed before they are left in the repository.

The panel that already existed

Before this I had built another piece in the same direction: an operations panel for the webhook pipeline, so that Customer Support can diagnose a case without escalating it to engineering. You search by store, provider and event type, you see the processing state live, and each order has its timeline with all its events chained by correlation ID.

Logs explain what a process did, but they can be sampled or have expired. The current state and its history of transitions live in a durable entity, and that's where it's best to read what happened. Logs and traces point to that state, they don't replace it.

It's the same idea from two sides: making the path between "something has failed" and "I know exactly what happened" short.