Your career has a Single Point of Failure
And it’s way riskier than you think.
Newsletter platform + open networkNewsletter platform with an open network built in
Sending, automations, your own domain and website, and a full API and MCP server. Or keep Kit, Ghost, Beehiiv or Substack. Either way, every post joins an open network of newsletter communities.
Free to connect Sending from €9/month API & MCP docs
Have an account? Log in
This is Commune, live. Every card is a post from an independent newsletter. Tap the numbered dots for a quick tour.
This is Commune, live. Every card below is a post from an independent newsletter, with its own conversation. Read anything without an account. The numbered dots give you a 30-second tour.
Every card is a post from an independent newsletter. The label shows where it was sent from: Commune, Kit, Ghost, Beehiiv, Substack and more. The network works the same wherever you send from.
Depends on what. In general, I don't care it's a robot if it's doing its job right. So yeah, in practice, I'd pay more for humans 😄
And it’s way riskier than you think.
Es un buen punto de vista, sobretodo empezar a diversificar. No es necesario dedicar mucho tiempo, solo “romper el hielo”. PD: Qué difícil es eso de ahorrar con criaturas jajajaj
For writers
Connect it and your archive and every new issue land in this feed, each with its own conversation. Keep sending from where you are, or move your sending to Commune.
> Building has never been this cheap, so > now I can start, finish, and drop a project in a single > weekend. LOL, that's true 🤣
Iba a titular este correo “Las decisiones caras son las que no toma nadie” pero, ¿no te parece que ya todo suena a IA? Es superinquietante. Y bastante mierdero. Así que he decidido escribir este correo con más mala leche de lo habitual, activo el modo leche agria de 3 días, agárrate a la silla que despegamos (no como los de EEUU, que siguen en tierra, juajajajajuajajja). Joder, si hasta escribo con efectos especiales, esto en tu cabeza ha sonado a risa de malo de peli de serie B, soy la hostia. Al lío. Que el viernes, no contentos con joder el correo de medio mundo, los USA decidieron cagarla mandando a tierra todo su tráfico aéreo durante horas. Por lo visto le echan la culpa al del wifi. Sí, se ve que están cambiando los cables de cobre por la fibra y el viernes algo salió mal, un router empezó a volverse loco y colapsó las comunicaciones, con lo que no era seguro mantener el tráfico porque las pantallicas de los controladores no pirulaban. Esto último no sé si fue así, pero me da gustico pensar en los controladores jugando al buscaminas porque se había caído la red. Esto del router, ¿excusa o excusa de mierda? Excusa de basura del tamaño de Michigan. A ver cómo te lo cuento… El abc de un proceso de migración es que nunca, bajo ningún concepto, never, niente, por ahí no, repito, nunca se corta tráfico en momentos de pico. Si hay que cambiar un sistema por otro se hace de noche o cuando hay poca carga. Esto aplica a la telefonía, a una aplicación de negocio o al tráfico aéreo. Cortar un viernes por la tarde es como hacer una actualización del CRM en pleno black friday. No se hace. Punto. Así que, o es mentira, o alguien ha sido tan incompetente que su cabeza debería estar en una pica en Desembarco del Rey. Mira, vale ya de echar balones fuera. La causa ha tenido que ser otra. Si no, son una panda de negados. Y esto es todo lo que diré sobre este tema. Jorge - Head of Migrations ¿Te has reído? Pues que se note. Compartir
API + MCP
You can't design event-driven systems in Markdown specs When modules interact by choreography, the design can't be properly described and reviewed in Markdown. It needs a model structured enough to capture the interactions, and short enough for a human to approve before the agents start. Colin Eberhardt put Spec Kit through its paces, and one CRUD feature produced about 2,577 lines of Markdown for 689 lines of code. Reviewing it took him around three and a half hours. I don’t know about you, but I can’t read Markdown as fast as LLM agents can write it. But to leverage autonomous agentic loops you do need specs. You need a specification that is sharp and concrete, detailed down to the level where the agent doesn’t need to ask. Otherwise, working prompt by prompt, you stay tied to the chat, prompting, correcting, prompting again and constantly steering. Spec-driven development is the right move, but getting to a spec that is complete and concrete enough comes with its own problems. This article is about those problems, and about a complementary approach to fix them. 1. The problem To get such a spec you have two options: You write it by hand, and you may end up writing more text than the code itself. You let the agent write it for you after maybe an interview or grilling session, and you may end up with a huge Markdown spec that you need to review. Most teams these days, and for good reasons, go with the second option. But that’s how you end up with 2,577 lines of Markdown for a feature that took 689 lines of code, and I expect most of those were just boilerplate that is very easy to review. And that is a problem: approving a spec without fully understanding it, you’re letting the agent make decisions for you. The context you share with the agent inevitably contains gaps, and whatever you didn’t say, the agent fills in. I have found, time and time again, that if I push back against some architectural decision that I want to postpone and come back to later, the agent anchors the spec to that decision and works around it, as if it were written in stone. The right context was that I was just postponing it, but I missed conveying the intent, and the agent filled the gap. And in an agentic loop, this gets worse because the spec is the root of your task breakdown and of the context for each and every implementation. So these leaked constraints become constraints for every task that comes after, and the agent takes them as gospel. There is another thing I see in how SDD tools organize the spec. In Spec Kit, spec.md describes the behavior: user stories and acceptance scenarios, what the system does seen from outside. Design does exist, but in other files (plan.md, data-model.md, contracts/…), also in Markdown and generated by the LLM in the planning step. In my experience, designs in Markdown are way harder to understand and approve. The designs I see in these files are mostly stack choices and data models, rarely architectural decisions: which events a module publishes, who listens to them, which calls are direct, how the APIs interact with each other… I can’t know what every team is doing, so take this as an impression from what people have shared in the last few weeks. I believe that you can hardly design complex systems using Markdown files. By complex I mean systems with many pieces that have to work together, where no single module owns the behavior. Let those pieces be anything that owns its data and its state, and that the others reach only through commands and events. It can be a microservice, a module inside a monolith or a bounded context. Which one doesn’t matter here. I say event-driven in the title as a shortcut, because it is the clearest example: the modules interact by choreography, each one reacts to the others, and nobody holds the whole flow. But a monolith with several modules has the same problem. The system is distributed across modules, with or without a network between them. Orchestration is somewhat easier, because the flow lives in one place you can review, the orchestrator. The hard case is when nobody owns the flow. If you leave out the design, the agent will invent the architecture and apply patterns no architect approved. With many moving pieces you need a structured spec that can work as a system blueprint. With only Markdown, I expect you will end up with a Big Ball of Mud. 2. Why not better Markdown, or the API specs we already have? The obvious answer is to write better Markdown: templates, one section per decision, ADRs… Templates help, and if you use Markdown specs you should use them. But text must be interpreted. Every time an agent or a person reads a Markdown spec, they have to rehydrate the context and interpret the words again. Tomorrow, in another session with another context, they read the spec in a different way. The spec didn’t change, it was the interpretation that changed. We already have structured formats that don’t have this problem, and I use them every day. I’m a TSC member and an ambassador of AsyncAPI, so if I write about designing event-driven architectures I have to talk about it. In AsyncAPI, and in OpenAPI, the vocabulary is closed: channels, operations, messages, schemas… With AsyncAPI and OpenAPI it is easy to describe what a module provides and how to interact with it, but you can’t describe how the system glues together. You can’t describe a choreography with them: which event triggers which command, state transitions, compensations after failures… You can describe the edge of a module very well, but that’s about it. Causality can’t be described in any of these formats, and in practice you end up tying the files together with Markdown prose, and whoever reads it has to rebuild the flow in their head. And that is both a bottleneck for humans and room for interpretation for agents. Diagrams as text are another option, Mermaid or PlantUML, and LLMs understand them well. They help you view different aspects of the system and are a clear step forward for review. But as a design language they fall short: an arrow in a diagram can mean anything, and a sync call looks the same as an event. You can fix that with a convention, but then the team has to agree on it and learn it first, and after that you depend on the agent understanding it the same way, every session. With C4 I can show the boxes and how they relate. Then there is Arazzo, the workflow format of the OpenAPI Initiative. Since 1.1 (May 2026) it accepts both OpenAPI and AsyncAPI documents, so it can sequence sync and async calls. But an Arazzo workflow is for orchestrations driven from a single place, and it can’t describe choreographed interactions. The problem with all these formats is that you still depend on Markdown prose to glue everything together. When systems were developed one line of code at a time, with lots of human interaction and coordination, that glue was shared and tribal understanding. But if we want to leverage autonomous agentic loops, we need to write down how everything works together, upfront, in a format humans can read and approve, so agents can work on their own. What I’m missing is a structured language for the design itself, one that has a closed vocabulary rooted in years of software engineering practice like Domain-Driven Design: aggregates, entities, value objects, commands, domain events, bounded contexts… And from other techniques like Clean Architecture, Hexagonal Architecture or Ports and Adapters, and Event-Driven Architectures: ports, adapters, inbound and outbound, publishers, subscribers, channels… These words already mean the same thing to most developers and to the LLMs, which learned them from the same books and code. I’m not proposing to go back to heavy UML tools. I’m talking about lightweight structured representations, in plain text, that: you can keep in Git you can diff and review in a pull request you can include in the context of an agent an agent can read and write a human can understand and approve without drowning in prose and have enough structure to be validated and linted, and agents and humans can reason about that structure and not about free text So this is the opinion I want to put on the table with this article: systems whose behavior lives between modules cannot be properly described, designed and reviewed in Markdown. Event-driven architectures are the clearest example. Even a single module is hard. 3. The fix: blueprints My proposal is that the spec describes the behavior and also how to build it, stopping just before the code. Like a blueprint. The tools for this already exist: modeling techniques and structured languages that describe interactions, contracts and architecture. The vocabulary is the one from the DDD patterns most of us already know (aggregates, entities, commands, domain events, services…), so there is a syntax to learn but no new concepts. In practice this requires a flow model for describing how modules interact in a business process, plus one domain model per module, describing its inner domain and what it receives and publishes, whether synchronously or as events. So a specification becomes a domain-model blueprint, not a text document. As an example I use the checkout of Arcadia Editions, a fictional company I use to write about these things. It is one example of the problem, not its definition. The orders module and the payments module are about 170 lines each, including configuration and comments. Each one describes its persistence, the commands it receives, the events it publishes, the events it listens to from other modules, and the direct calls it makes to them. The models are written in ZDL, the domain language of ZenWave, an open source toolkit I created. The flow model is written in ZFL, its flow language. Any structured language with the properties listed above would do. The checkout is a choreography of six modules that exchange messages, with nobody orchestrating. This is what happens when fulfillment fails: fulfillment fails and publishes FulfillmentFailed payments listens, voids the authorization and publishes PaymentVoided inventory listens, releases the stock and publishes StockReleased orders listens, cancels the order and publishes OrderCancelled notifications listens and tells the customer In Markdown this chain would be spread across paragraphs in five documents, and you would have to rebuild it in your head to review it. In the flow model it is in one place. This is the compensation part of the checkout flow, without the comments: @compensates(authorizePayment) when FulfillmentFailed, PaymentCaptureFailed do voidPayment { service PaymentsProcessing.PaymentsProcessingService emits PaymentVoided } @compensates(reserveStock) when PaymentDeclined, PaymentRetryExhausted, PaymentVoided, ReservationExpired do releaseStock { service CatalogInventory.InventoryService emits StockReleased } @compensates(startOrderCheckout) when StockReleased do cancelOrder { service OrdersCheckout.OrdersCheckoutService emits OrderCancelled } when OrderCancelled do sendOrderCancelledNotification { service NotificationsConsumer.NotificationsConsumerService emits OrderCancelledNotificationSent } Each step says what triggers it (when), which module owns it (service), what it emits, and what it compensates. AsyncAPI says what crosses the edge of each module. The flow model says how the modules cause each other. Then each module owns its steps in its own domain model. These are the three commands of the orders module that change the state of an order. The comments are added for this article: @rest("/orders") service OrdersCheckoutService for (Order) { // A REST command. It calls inventory directly to reserve the stock. @post("/start-checkout") @transition(to: CREATED) @calls(zdl: CatalogInventoryZdl, command: InventoryService.reserveStock) startOrderCheckout(StartOrderCheckoutInput) Order withEvents [OrderCreated | StockUnavailable] // Reacts to an event published by the payments module. @listener(zdl: PaymentsProcessingZdl, event: PaymentAuthorized) @transition(from: CREATED, to: CONFIRMED) @calls(zdl: CatalogInventoryZdl, command: InventoryService.confirmStockReservation) confirmOrder(ConfirmOrderInput) Order withEvents OrderConfirmed // Reacts to an event published by the inventory module. @listener(zdl: CatalogInventoryZdl, event: StockReleased) @transition(from: [CREATED, CONFIRMED], to: CANCELLED) cancelOrder(CancelOrderInput) Order withEvents OrderCancelled } Every command reads the same way: what triggers it (@post or @listener), which state change it is allowed to make (@transition), which direct calls it makes to other modules (@calls), and which events it can publish (withEvents, with | between alternative outcomes). Following the @listener and withEvents of each model you can read the same chain the flow model describes. The fourth step is cancelOrder in the snippet above: it listens to StockReleased and publishes OrderCancelled. And this is the second step, in the payments module: service PaymentsProcessingService for (Payment) { // ... // Voids the payment when fulfillment fails, or when its own capture fails. @listener(zdl: FulfillmentShippingZdl, event: FulfillmentFailed) @listener(event: PaymentCaptureFailed) @transition(from: [AUTHORIZED, AUTHORIZATION_REQUESTED, FAILED, CAPTURE_FAILED], to: VOIDED) voidPayment(VoidPaymentInput) Payment withEvents PaymentVoided } Direct calls are visible in the same way. In the orders service above, startOrderCheckout has an @calls to InventoryService.reserveStock: orders calls inventory synchronously to reserve the stock, and doesn’t wait for an event. It is one line that someone has to see and approve, or change. The models are short because the vocabulary carries the meaning, so there is no need to explain in prose what @listener or @transition mean. Compared with SDD, the spec is still the unit of work, only now it is a model instead of prose. Compared with the old model-driven software development (MDSD), the model is not about complex CASE tools and heavy UML diagrams to generate everything from. CASE and MDA tools could only give you lexicon and structure, and the semantics had to be filled in by hand, by the people writing the generators and templates. That is where they fell short. What has changed is that now lightweight text formats give you the lexicon and the structure, and the LLMs fill in the semantics. I concede that you could do something similar in Markdown, with a strict template and a lot of discipline. But then the structure lives in the discipline of the author, and the next spec, or the next agent, may not follow it. I prefer the structure to live in the language, where a parser can check it. What I get from this: I can read a module in one sitting, before lunch an agent can cross-check all the contracts at once: published events with their listeners, listeners with events that exist, inputs with the fields they need… decisions that leak have a visible form in the model, like an @calls that nobody asked for 4. The limits A short model can still be wrong, of course. While preparing this article I reviewed the checkout models again with an agent, just to find inconsistencies between the linked models and this article, and we found gaps I hadn’t seen before. The worst one is a race between the reservation timer and a payment retry. If the payment is still pending after 10 minutes, the scheduler fires ReservationExpired and inventory releases the stock. Orders listens to StockReleased and cancels the order. Notifications tells the customer no payment was taken. But if a retry was already in flight, it can still succeed after all that and publish PaymentAuthorized. Orders tries confirmOrder, which fails because the order is already CANCELLED, and there is no listener in payments to void that authorization. The customer keeps a hold on the card for a cancelled order. Each module did the right thing by its own model. The failure lived between modules, in the interleaving of the timer path and the retry path. A sequence diagram shows one scenario, so it would not have shown this one. The timer, the @transitions and the @listeners were all in the models. My workflow even has an agent skill for this kind of cross-check, and it didn’t catch it. We found it this time because we were going through the models against the article. These gaps need an explicit review step, and in my case even that wasn’t enough. So the model didn’t find the bug for me. But once found, I can point at it. confirmOrder only accepts from: CREATED, cancelOrder has already moved the order to CANCELLED, and voidPayment has no @listener for an authorization that arrives late. In the flow model, ReservationExpired is one of the triggers of releaseStock. That is three lines in two domain models and one in the flow, all of them shown above, and the fix will be a small diff that someone can review. I don’t know where this bug would live in a Markdown spec, or which lines I would point at. Model checkers are built for this kind of thing (states you can reach but can’t leave, races between timers and events…). I don’t think you can do formal verification on Markdown, but with lifecycles, transitions, listeners and timers declared in a model, most of the input is already there. This is still a hypothesis, and I’ll explore it in the next article. There is also a cost: a new language to learn and tooling to maintain. For a prototype, or something you will throw away, I would just use Markdown. Closing Working prompt by prompt has a ceiling, and agentic loops are how you go past it. But a loop is only as autonomous as the spec it starts from. For this loop to work, the spec needs to cover enough work for an autonomous AFK loop to be worth it, and to be complete and detailed enough that the agent doesn’t hallucinate the details. And, more importantly, such a spec only works if a human can read it and approve the design decisions inside it. For systems whose behavior lives between modules, event-driven or not, I don’t believe this can be done in Markdown. It needs a document small and structured enough to be read, where humans keep making the design decisions: a domain-model blueprint. I call this approach Domain-Model Spec-Driven Development (DM-SDD), and I wrote about it here. How do you review your specs today? Originally published at ivangsa.com.
This week saw the resignation of Jensen Huang, air traffic control outages in the US (though possibly not AI related), and AI self improvement acceleration.
That pissed me off so much that I wrote my process down so I never forget again.
Thank you for sharing your wins and failures. We all learn from sharing what works and what doesn't.
By mid-morning most of us are curled towards the screen. This is a five-minute seated upper-back opener to start the week, guided by counts so you can look away from the monitor. Seated cat and cow (about 1 minute). Hands on your knees. Breathe in and lift the chest, letting the shoulder blades draw together. Breathe out and round the upper back, chin towards chest. Eight slow rounds. Thread-the-needle against the desk (about 2 minutes). Slide your chair back. Place one forearm on the desk edge and reach the other arm under it, letting the upper back rotate gently. Hold for five breaths, then switch. Chair-back chest opener (about 1 minute). Clasp your hands behind the chair back, or hold the seat edges, and gently lift the chest. Hold for five breaths. Seated side reach (about 1 minute). Raise one arm overhead and lean slightly to the opposite side. Four breaths each side. Keep every movement easy and pain-free. If you have a back or shoulder condition, check with a qualified health professional first. Flexor App for stretching, from Flexor Labs, has short spoken guided routines like this that also work offline. — Flexor Labs
One of the challenges of software testing is deciding what to test. We spend considerable time developing testing frameworks and writing test scripts. But before that work begins, someone needs to decide which behaviors matter and what evidence would convince us that those behaviors work as expected. User stories offer a good starting point. They describe what people expect software to do, but rarely capture everything necessary to satisfy those expectations. How do we move from a short statement of intent to a useful collection of behavioral expectations? I’ve been working with a simple approach I call ERI: Explicit, Required, and Implied. The idea is to examine each user story from three perspectives, looking for hidden and implied behaviors that deserve further attention via test cases. Subscribe now Start with a user story Consider this example from an imaginary task management application: As a task manager, I want to mark a task completed so that I can distinguish completed work from active work. We could immediately design an API operation such as PUT /tasks/{id}/status and write a test that sends a request and checks for a successful HTTP response. But what have we learned? A successful response tells us something about the interaction, but it doesn’t necessarily establish that the system satisfied the original expectation. There is more here than we might see upon first glance. In fact, I think there are several tests “hidden” in this simple user story. Three questions Before writing tests, I find it useful to examine the story itself with a more critical or curious view. To do that, I ask three questions: Explicit: What behaviors does the story directly describe? Required: What additional behaviors must exist for the stated outcome to be satisfied? Implied: What other behaviors might reasonably be expected, given the story and its context? Each question offers a different perspective on the behavior of the system. Let’s apply them to our task management example. Explicit behaviors Explicit behaviors appear directly in the story. For example, our user story gives us this behavioral claim: A task manager can mark a task completed. Notice that, for now, we’ve avoided mentioning HTTP methods, resource paths, or implementation details. We’re interested in understanding what the story claims about the system before deciding how that claim will be implemented or verified. Required behaviors Next, we look for behaviors or conditions necessary to satisfy the explicit expectation. For example, the system needs to identify the task being completed. The system can identify the task targeted for completion. We also need some way to determine whether the operation succeeded. The completed state can be observed after the operation. These expectations carry consequences for API design and testing. What happens when the requested task doesn’t exist? How does the system represent successful completion? Can a client retrieve the resulting record and validate its state? The required category helps identify dependencies and supporting behaviors that deserve attention. Implied behaviors The third question explores expectations suggested by the story and its context. For example, marking a task completed raises questions about how long that completed state should remain in effect. A completed task remains completed until another authorized action changes its state. We might also wonder whether completed tasks can be reopened or whether unsupported status changes should be rejected. These are reasonable questions, but the original user story doesn’t establish their answers. An implied behavior is a candidate for investigation. It may reflect a domain rule, a common convention, or an assumption requiring confirmation. Applying ERI to a user story helps expose these questions before they become hidden assumptions in the implementation. From ERI to behavioral claims Our examination of the user story has produced several candidate behaviors worth considering for testing. Here we’ve expanded a short user story into behavioral claims for review with domain experts, developers, and testers. Some of these may become formal requirements. Others may be rejected or deferred. The important point is that we’ve made these expectations visible. The distinction between required and implied matters. Required behaviors follow from the stated expectation, while implied behaviors represent plausible expectations that still need confirmation. Choosing what to test Discovering candidate behaviors is only part of the work. We still need to decide which claims deserve verification and what evidence would support them. Consider our central claim: A task manager can mark a task completed. What observations would convince us that this behavior works? We might want evidence that: The target task exists and begins in an active state. The completion operation succeeds. A subsequent retrieval confirms the completed state. These observations provide stronger evidence than checking the HTTP response code alone. They also illustrate the distinction between behavioral claims and test assertions. A behavioral claim describes an expectation about the system. An assertion describes an observation that helps establish whether the expectation has been satisfied. A useful habit One of the things I like about ERI is how little machinery it requires. You can apply it during a design conversation, while reviewing a user story, or before writing an automated test. The process begins with identifying the behaviors stated in the story (explicit). From there, we examine the conditions necessary to support those behaviors (required) and explore additional expectations suggested by the surrounding context (implied). The resulting collection of behavioral claims provides a starting point for deciding what evidence to collect and which tests to write. Some assumptions will require further investigation before we’re ready to write tests. ERI won’t eliminate ambiguity or guarantee complete coverage, but it provides a repeatable way to expose behavioral expectations and decide which ones deserve verification. Every user story has more to tell us. ERI helps us find it. Subscribe now
If writing testing scenarios is something that AI could assist with (while deterministic tooling actually runs the test), could the ERI here be used to help AI design the tests?