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 😄
> Building has never been this cheap, so > now I can start, finish, and drop a project in a single > weekend. LOL, that's true 🤣
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.
I've actually been putting at the bottom of my articles "All em dashes in this article were handcrafted". But seriously, i know all of this, but don't practice it consistently. I need it tattooed on my brain in letters of fire, as they say. I have a page i use for tracking engagement and outreach and im gonna add this image to that page right now. Thanks so much.
Never have I ever been kicked out of a drag race. Until the summer I was 18, two months into my very first internship in America. It was a scorching hot day in Michigan, and our team was tailgating at a drag race. I'd moved from India to America at 17, was still figuring out the culture, and was very excited to be included in my first team outing. One of the guys turned to me and asked, "Archita, have you ever done donuts in a parking lot?" I hadn't. Naturally, he handed me the keys to his Subaru. With everyone cheering me on, I proceeded to do about fifteen donuts in the parking lot. I climbed out of that car feeling rather triumphant, delighted with my newly discovered driving abilities and the enthusiastic reception from my colleagues. My celebrations were short-lived. Three event officials came marching over, demanding to know who'd been driving the car. And, as you might imagine, every single person turned to look at the little 18-year-old Indian girl. "You need to leave. You've violated the event rules." I was mortified. My manager pulled me aside and told me not to say anything. He'd get me out of there. Now, you have to understand what was going through my head. I'd moved halfway around the world, was barely two months into my first internship, and was desperate to prove I belonged. I was convinced I'd just ruined everything. I was going to lose my internship, get fired, and somehow bring my entire American dream crashing down because I'd done donuts in somebody's Subaru. By the time we left the parking lot, tears were streaming down my face. And then my manager started laughing. "Archita, wipe those tears. Wear this cap. We're going to get back in there and watch that race!" And that's exactly what we did. For the rest of the afternoon, my manager and teammates looked out for me, and I got to enjoy my first adrenaline-filled drag race. What I remember most about that day, all these years later, is what my manager chose not to do. He didn't turn my mistake into a lesson. He didn't lecture me about professionalism or make an example of me in front of the team. He let me be 18, make a stupid decision, and recover from it. He could see that I was already terrified of the consequences. I didn't need someone to explain how badly things might have gone. I needed to know that one mistake wasn't going to define me. That experience taught me what kind of leadership makes people want to stay. Empathy matters most when someone is uncertain about what happens next. Creating a safe environment sometimes means stepping in and protecting people when things go wrong. Trust grows when people discover they can admit mistakes without fearing their careers will be over. I returned for a second summer internship and eventually spent 18 years with that company. That afternoon was one of the reasons I wanted to come back. Today, with layoffs, reduced budgets, and internal restructurings creating uncertainty across so many organizations, I think about that manager and the choices he made. Your people are already wondering what the next announcement means for their jobs, whether they're meeting expectations, and how much room they have to experiment or get something wrong. In those moments, the way you respond matters enormously. How are you showing up as a leader when your team is navigating uncertainty, taking risks, and occasionally getting things wrong? Because people may forget what you said in the last town hall. They are far less likely to forget how you treated them when they were scared. Until the next room, Archita Read the full note on readysetbold.com →
API + MCP
A comedy quote, depression, and what therapy taught me.
Qué importante es lo que comentas, @fmvilas Poco se habla de la exigencia que supone ser siempre un faro para los demás, sea el contexto que sea. Incluso fuera del trabajo. Te doy las gracias por abrirte de esa manera, que no debe ser fácil. Este mensaje nos ayudará a más de uno. Un abrazo 🫂
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.
I spent the first few years of my career getting very good at solving problems I increasingly wished we had found earlier. I was a quality engineer in Quebec, and when something went wrong with a product, there was no shortage of urgency. The product was already being used, a customer had a real problem, the business needed answers, and we needed to understand exactly what had happened and make sure it did not happen again. Give me a complicated problem where the first explanation did not quite make sense, and I could happily disappear into it. I wanted the data, the engineering, the process, the customer experience, all the different versions of what people thought had happened, and somewhere inside all of that was usually the actual answer. There was something incredibly satisfying about finally finding it. But after doing this for a while, I started having one fairly irritating thought. Why are we learning this now? By the time we were asking some of our best questions, the product had already been designed, built, launched, and put into a customer’s hands. Now we were intensely interested in what the customer had experienced, what they had expected, how they were actually using the product, what had gone wrong, and why our assumptions didn’t match reality. I kept wondering… What would happen if we put some of that energy into understanding those things earlier? What if we spent more time with customers before we built the product? What if we understood how they worked, what frustrated them, what mattered to them, and what problem they really needed us to solve before we got terribly attached to our answer? Around the same time, I gave a presentation on a fairly complicated quality situation we were navigating. A VP of Marketing named Kevin happened to be in the audience, and afterward he came up to me and said, “If you ever want a job in marketing, give me a call.” This was not an obvious career suggestion at the time. I was an electrical engineer working in quality. I had never worked in marketing and had no grand plan to become a marketer. I remember being pleased that he thought I might be good at it, and then I went back to my actual job. Four to six months later, my assignment in Quebec was coming to an end, and the company offered me a promotion to Senior Quality Engineer. I had worked hard for it. I was doing well, and it made complete sense, but I remember thinking about the new role and feeling bored. Not because I was bored with solving problems; I loved that part. I was bored by the thought of spending the next few years getting even better at solving them after the product was already out there. I wanted to be closer to the customer before we built something. I wanted to understand what they needed, what we should build and why, and whether the thing we were excited about inside the company actually solved something useful outside it. So on a random Friday afternoon I picked up the phone to Kevin and said, “Hey Kevin, you told me that if I ever wanted a job in marketing I should give you a call. This is that call.” That was how I ended up in marketing. When I tell people this story now, they usually stop me at the same place. “Wait, you were an engineer?” The move from engineering into marketing tends to become the interesting part of the story. Looking backward, I can certainly make it sound very intentional. I moved into product marketing, launched products around the world, worked through acquisitions, built and led global teams, and spent much of the next two decades getting closer to customers and the commercial side of businesses. Careers become remarkably easy to explain once you already know how they turned out. What interests me much more now is the question that was already bothering me before I had any idea where my career was going. Why are we learning this now? I see versions of it in businesses all the time. A product launches and customers do not respond the way everyone expected, and suddenly we get very interested in talking to them. The sales team misses the number, and now we want to understand whether customers actually care about what we are selling, whether sales believes the story they have been asked to tell, and whether the pipeline was ever as healthy as everyone thought it was. An acquisition closes, and months later people start asking very specific questions about how the two businesses are supposed to work together, who owns what, where customers overlap and what exactly “integration” was meant to look like. A senior hire does not work out, and suddenly everyone can describe, in remarkable detail, what the role actually needed. None of this means those decisions were bad or that we could have predicted every problem. Markets move, customers surprise us, and people behave differently than we expected. Strategies that looked sensible with the information available at the time sometimes simply do not work. Sometimes you genuinely could not have known. What I find more interesting are the times when we could have known or at least known enough to ask a better question. Because something changes once the problem becomes expensive. We find the time to call the customers. We pull apart the pipeline instead of discussing the number at the top of it. We put sales, marketing, and product in the same room and make everyone explain what they are actually seeing. We talk to the people closest to the work. We go back to assumptions that sailed through three previous meetings and ask whether they were ever true. The questions were available before, but the urgency around answering them wasn’t. I recognize that because I spent years on the other end of it. As a quality engineer, I was trained to go into a problem once reality had told us something was wrong and understand exactly what had happened. I still love doing that; I have just become much more interested in whether we can ask some of those questions while there is still time to change the decision. That starts with looking at what you are scrambling to understand now. If a product is struggling and you are suddenly spending hours talking to customers, what are they telling you that would have been useful six months ago? If the pipeline has fallen apart and you are finally examining every opportunity, what are you discovering that the headline number kept you from seeing? If an integration is stuck and everyone is now arguing about ownership, what did you assume would somehow sort itself out after the deal closed? Then there is a second question, and I think this is the one that matters more. Where else are we making a decision today without that information? Because fixing the immediate problem is only part of the value of learning something late. A weak product launch can teach you how well your company understands customers before it decides what to build. A missed quarter can tell you something about how easily a room can accept a pipeline number without understanding what sits underneath it. A difficult integration can expose assumptions that are probably sitting inside the next acquisition plan too. The useful part is not writing those things into a lessons-learned document six months later. It is getting them into a decision that has not been made yet. So the next time everyone in a room is working furiously to understand what went wrong, stay there a few more minutes before fixing it and moving on. Ask: What do we know now that we wish we had known earlier? What made us finally go looking for it? Where else would knowing this now change a decision we have not made yet? You cannot change when you learned it the first time. You can make sure you don’t learn it late twice. Until the next room, Archita Read the full note on readysetbold.com →
Great post... I'd even add one thing -> when in Q&A and product you only have one lever : fix the product. But actually it may be another lever that's wrong -> the wrong type of user. That's one of the best things to learn about early!
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.
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?