In B2B SaaS, losing customers to mechanics rather than intent is an avoidable operational leak. When account termination is treated as a back-end database task instead of a critical product journey, churn numbers mask a deeper failure of workflow design.

The silent drain of involuntary churn#

In assisted-onboarding products where sales teams drive initial acquisition, customer acquisition cost is high. Weeks of relationship building, contract negotiation, and security reviews go into landing a single business subscriber. Once onboarded, that subscriber’s intent to use the product is established.

Yet, data consistently shows that a measurable percentage of churn is entirely involuntary. Customers do not leave because they found a competitor or rejected the pricing. They leave because: - A corporate credit card expired or failed an automated payment mandate. - An annual renewal invoice was sent to an accounts payable email address that was rotated out after staff turnover. - A grace period script executed a hard deactivation after seven days without alerting the account relationship manager.

To a naive product metric, these accounts simply appear as churned cohorts on the monthly dashboard. The product team responds by building new feature upsells or engagement loops to win them back, assuming the product failed to deliver value. In reality, the customer was ready to pay, but the system refused their money.

Payment Failure Occurs → 7-Day Hard Cutoff → Account Suspended → Relationship Manager Unaware → Permanent Churn

When you treat billing failures as customer churn, you diagnose a mechanical problem with a product solution. You end up shipping retention features to users who never wanted to leave in the first place.

When data is the product, churn costs twice#

The cost of involuntary churn is magnified significantly in B2B data-network products—such as credit bureaus, vendor rating platforms, accounts receivable databases, and supplier directories.

On a standard software-as-a-service platform, a churned user represents lost recurring revenue and nothing more. Their departure frees up database storage and server compute. On a data-network platform, however, every member is both a consumer of intelligence and a contributor of proprietary data.

On a B2B credit-data SaaS I worked on, we discovered that account deactivation had compounding downstream consequences:

1. The contributor loss: When a business member was cut off due to a lapsed billing cycle, their active debtor reports, payment defaults, and trade credit records were pulled offline.
2. The network degradation: Because every other member’s credit assessment relied on the collective pool of reported trade experiences, losing a contributing member slightly degraded the data coverage for all surviving members.
3. The acquisition treadmill: Re-acquiring a churned business customer costs nearly as much as landing a new one, but recovering them requires overcoming the friction of a broken relationship.

A data-network product does not just lose revenue when a member is cut off prematurely; it loses the proprietary inputs that make the product valuable to everyone else.

Deactivation cannot be left to a cron job that checks an invoice table and flips a boolean flag in the user database. Cutting off a business account is a high-stakes product decision that requires orchestration across billing, customer success, and data integrity.

The manual invoice paradox#

There is a recurring irony in financial technology and B2B SaaS startups: companies that sell sophisticated automated receivables management, invoicing portals, and cash-flow forecasting tools to their clients often run their own internal billing operations through manual spreadsheets, ad-hoc payment links, and scattered email threads.

When internal billing is manual, finance teams spend hours reconciling bank transfers against accounts, matching invoice IDs, and manually notifying customer success when a payment lags. Because the feedback loop between the bank account and the database is slow, customer accounts are frequently flagged as unpaid while the wire transfer is already clearing in the clearinghouse.

During an audit of our retention and billing flows, we found that a significant fraction of escalations labelled as “pricing pushback” or “subscription cancellation” were actually accounts where finance had mailed an invoice to an unmonitored inbox, received no response within an arbitrary window, and requested a system-level suspension.

Fixing this required treating internal invoicing with the same product rigor applied to customer-facing features: - Centralized billing states: Connecting payment gateway webhooks directly to account status tables so that subscription renewals update instantly without manual intervention. - Relationship manager visibility: Routing failed payment alerts into the internal CRM dashboard of the account owner 72 hours before any automated restriction triggers. - Tiered grace handling: Differentiating between a first-time payment failure (where corporate card updates are common) and a deliberate cancellation request.

Designing deactivation as a product journey#

To stop leaking revenue through administrative gaps, deactivation must be elevated from a database script to a first-class product workflow.

When you redesign account suspension around how businesses actually operate, several principles emerge:

1. Never deactivate without human context: If an enterprise or high-value SMB account hits a billing wall, the account relationship manager must be notified before the user is locked out. A five-minute phone call from an account lead resolves more billing failures than fifty automated reminder emails.
2. Preserve data integrity across suspensions: In network models, maintain contributor records in a read-only or quarantined state during grace periods so that aggregate reporting remains stable while commercial terms are sorted out.
3. Make payment recovery frictionless: When a user logs in during a grace period, present a single, prominent payment recovery banner with multiple checkout rails (UPI, corporate card, net banking) rather than directing them to contact support.

The operational checklist for billing resilience#

Before your team prioritizes new acquisition features or roadmap expansion, audit your current account lifecycle infrastructure against these four operational rules:

• Audit your grace periods: Measure how many days elapse between an initial payment failure and a permanent account lockout. If it is under seven days in a B2B context, you are firing customers over temporary banking delays.
• Trace the notification path: Verify whether your billing alerts go to the person who holds the corporate card or to an abandoned AP inbox that nobody checks.
• Connect billing state to your CRM: Ensure that account managers receive an in-app or Slack notification the moment a key account enters payment grace, long before the user experiences a service interruption.
• Treat billing code as core product logic: Subject your invoicing, retry schedules, and deactivation scripts to the same rigorous code reviews, automated testing, and QA cycles as your core user-facing features.

Demand is hard to win and expensive to acquire. Do not let administrative mechanics throw away customers who already want to stay.

The drop-off is rarely caused by user hesitation, payment friction, or confusing typography. It happens because the user tried to buy, and the product said no.

The phantom funnel leak#

Standard product analytics aggregate actions into a single linear progression:

app_opened → signup_completed → address_entered → service_selected → checkout_completed

Between address submission and checkout, the line falls off a cliff. Product managers look at the chart and assume friction: Was the address picker difficult to operate? Did the pricing surprise the user? Did the service description fail to build trust?

In reality, the user typed their home address, selected a date, and hit a blocking dialog: “Service is currently unavailable in your area. We will notify you when we expand to your neighborhood.”

The user did not abandon the funnel. The product abandoned the user.

When you collapse that rejection into a generic drop-off step in Mixpanel or PostHog, your analytics tell a misleading story. The marketing team celebrates meeting its cost-per-install target while complaining that product conversion is soft. Meanwhile, product engineering spends sprint capacity tuning onboarding screens that were already functioning as intended.

What 70% unavailable looks like in the data#

At a services marketplace I worked on, we spent weeks investigating why acquisition cohorts showed an agonizing drop-off between account setup and the first completed booking. The growth dashboards were full of theories about onboarding friction and price sensitivity.

When I stepped back from the standard funnel and audited what users actually encountered after entering their address, the real bottleneck became obvious: 70% of users who checked eligibility saw “unavailable” at least once.

Think about what that denominator means. Out of every ten qualified users who downloaded the app, completed registration, and told us exactly where they lived, seven were turned away by our own software.

An unavailable screen is not an edge case or an operational footnote. It is an unfulfilled purchase order.

Marketing was hitting its download targets and burning ad spend across major metropolitan pin codes, but our field partners were clustered in a handful of tight residential pockets. We were paying full acquisition costs to deliver a rejection notice to seven out of ten prospective customers. Worse, a user who is told “service unavailable” does not patiently wait for your ops team to recruit partners. They uninstall the app, solve the problem through an unorganized local vendor, and rarely return when you eventually launch in their sector.

The geometry of urban Indian supply#

Hyperlocal services in Indian cities face physical constraints that centralized e-commerce platforms never encounter. You cannot treat a city like Mumbai, Bengaluru, or Delhi NCR as a single operational zone or a neat radial circle.

Urban density in India fractures service radiuses. In Mumbai, a field partner based in Bandra West cannot reliably take an 11:00 AM booking in Kurla, even though the straight-line distance is only six kilometers. Railway crossings, arterial traffic bottlenecks, and monsoon waterlogging turn short physical trips into hour-long commutes. In Bengaluru, crossing the Outer Ring Road during peak hours breaks partner punctuality and destroys schedule predictability for the rest of the day.

Furthermore, address checks fail for two completely distinct reasons:

1. Geographic absence: The submitted location sits outside any active partner polygon.
2. Temporal exhaustion: The location is inside an active polygon, but every available partner is already booked for the requested morning or evening window.

Both conditions present the exact same message to the customer: Service unavailable. But one is a partner recruitment problem, and the other is a slot scheduling and dispatch problem. If your analytics cannot tell them apart, your operations team cannot fix either.

Instrumenting rejection as a demand signal#

To turn supply coverage into a growth lever, you must treat every address check as a structured demand event rather than an incidental view.

Event: service_eligibility_checked
Properties:
  - latitude: 19.0760
  - longitude: 72.8777
  - pincode: "400051"
  - service_category: "home_grooming"
  - requested_slot_start: "2026-11-01T10:00:00Z"
  - outcome: "unavailable"
  - rejection_reason: "slot_exhausted"  // or "out_of_coverage"
  - active_partners_in_polygon: 4
  - attempt_count: 2

By logging the exact rejection reason and geo-coordinates, the “service unavailable” screen stops being ops noise and becomes your supply acquisition roadmap:

• Demand clustering: Aggregating coordinates reveals high-intent clusters that span across arbitrary postal pin code boundaries. You can see exactly which two-kilometer micro-markets have enough density to justify recruiting new partners.
• Slot elasticity: Logging requested timestamps highlights where demand spikes exceed capacity. If 80% of rejections in a zone happen between 8:00 AM and 11:00 AM on Saturdays, hiring more full-time partners is the wrong answer; you need part-time weekend shift incentives.
• Repeat intent: Tracking attempt counts separates casual browsers from frustrated buyers who returned three times trying to find an open slot.

The supply coverage audit#

Before approving another marketing budget increase or commissioning an onboarding redesign for a local services product, run this diagnostic on your last 30 days of data:

1. Calculate the Supply Coverage Ratio (SCR): Divide the number of eligibility checks that found an open slot by the total number of eligibility checks submitted. If your overall SCR is below 60%, pause paid acquisition campaigns immediately.
2. Segment SCR by micro-polygon: Identify the specific neighborhoods where SCR exceeds 80%. Confine paid performance marketing strictly to those geofenced boundaries.
3. Split rejections by cause: Measure the ratio of out_of_coverage versus slot_exhausted. Use the former to guide partner onboarding targets, and the latter to restructure partner shift incentives and weekend payout multipliers.
4. Remove supply drops from the product funnel: In your primary conversion dashboards, separate users who had access to inventory from users who were blocked by coverage. Measure product UX performance only on the cohort that could actually buy.

In hyperlocal marketplaces, product design and operations cannot operate in silos. When conversion drops, check the street before you refactor the code.

The mid-tier is not a downgrade#

Terra is not a stripped-down version of the flagship. On Agents’ Last Exam, it scores within range of Astra at medium reasoning effort. On MMMU-Pro (visual reasoning), it nearly matches both Astra and Sol. The hallucination rate on error-inducing prompts dropped from 53.6% to 16.7% at low effort compared to the previous Terra generation.

This is meaningful because it changes the decision from “which model is best” to “which tasks actually need the premium tier.” If Terra handles invoice reading, form filling, and document drafting at a comparable quality level, the only reason to use Astra is tasks where its remaining edge — the hardest code, the most complex multi-step reasoning — is the bottleneck.

Price cuts create re-architecture decisions#

A 50% price drop does not just save money on existing usage. It makes previously uneconomical tasks viable. An application that could not justify AI-assisted data entry at $2 per million input tokens might clear the business case at $1. That is not a small operational tweak — it changes what you build next.

For a PM managing an AI-powered product, the practical questions after a pricing shift like this are:

• Which tasks are currently on the premium tier that Terra could handle? Run a sample of production inputs through Terra and compare output quality. If completion rates and accuracy are within your error budget, migrate those tasks and redeploy the savings.
• Which tasks were rejected on cost grounds? Re-run the unit economics. A task that cost $0.12 per completion on Sol might cost $0.06 on Terra. If your product charges $0.50 per use, that margin change is significant.
• Where does latency matter more than capability? Terra completes tasks over three times faster than Astra. For user-facing features where wait time affects conversion, the faster model at lower cost is the better product choice even if the premium model scores a few points higher on a benchmark.

Track cost per task, not cost per token#

Token pricing is a proxy, not the metric that matters. Two models at the same per-token price can have very different costs per completed task if one uses fewer tokens or fewer retries to reach the same outcome.

OpenAI’s own framing hints at this: they report that Terra is “over three times as token efficient as Claude Opus 5.5” on computer-use tasks, resulting in roughly 9x lower cost per task. The efficiency gain compounds with the price cut.

A useful internal dashboard for any PM shipping on top of LLM APIs tracks three numbers per task type:

If you only track cost per token, you will miss the moment when a cheaper model actually delivers a lower cost per task because it is more efficient. You will also miss the moment when a premium model is worth its price because it avoids expensive failure recovery.

A lineup is a portfolio strategy#

What OpenAI is doing with Terra, Sol, and Astra is not just releasing better models. It is building a pricing portfolio: a set of options at different price-performance points, each designed to capture a segment of demand that the others leave on the table.

This is a familiar pattern in enterprise software (Salesforce editions, AWS instance families), but it is newer in the foundation-model market. For PMs building downstream products, it creates real work. You need to map your task types to model tiers, set rules for when to route up or down, and monitor whether the boundaries are still right after each new release.

The risk of not doing this is straightforward: you either overpay by using the premium tier for every request, or you under-deliver by using the cheapest model for tasks that need more capability. Neither is a good default.

The decision rule#

After a major pricing shift like Terra, I would run this sequence:

1. Inventory your task types by volume, current model, and current cost per completion.
2. Sample-test the new tier on your top-five highest-volume task types.
3. Compare completion rate and quality against your error budget, not against the premium model’s maximum score.
4. Migrate tasks where the new tier meets the bar, and track the cost and quality delta for two weeks before committing.
5. Re-evaluate rejected features that failed on unit economics at the old price point.

A model launch is not just a capabilities announcement. For product teams consuming these APIs, it is a pricing event that can reshape your product’s cost structure overnight. The teams that treat model selection as an ongoing portfolio decision — not a one-time architecture choice — will capture the margin before their competitors notice the price moved.

An override changes the operating rule#

Suppose a workflow normally routes a case for review when required information is missing. An operator bypasses that check because a specific case has an urgent deadline. The immediate action may be reasonable, but the system has now departed from its standard path.

That is more than a button click. It is a temporary policy change with a scope, a risk, and a future decision attached. If the product records only “override enabled,” it loses the context needed to decide whether the exception should continue.

A useful override record has five fields:

These fields make the exception legible to the next person. They also expose when an override is too broad: “all cases” may be a product change disguised as a workaround.

Make expiry a real state transition#

An expiry timestamp alone is not enough. At the deadline, the system needs a defined behavior. It might restore the prior rule, pause the affected workflow, or send the item to a review queue. Which choice is right depends on the consequence of reverting.

The important constraint is that expiry must not silently create a more dangerous state. If reverting a setting could interrupt a critical process, the product should warn the owner before the deadline and specify what happens if nobody responds.

For a low-risk formatting exception, automatic restoration may be fine. For a decision that changes what can be approved, expiry could instead move the case back to a pending state. The system should show the transition in the activity history, not make the user infer why behavior changed.

Keep extensions explicit#

Sometimes the exception is still needed when it expires. Let the owner extend it, but make the extension a new decision rather than a hidden reset of the clock.

A review card can show:

• the original reason and scope;
• what has happened under the override;
• the current expiry and return state;
• the options to end, extend, or replace it.

An extension should ask for a current reason and a new expiry. That small amount of friction distinguishes “still justified” from “nobody got around to cleaning it up.” If the same exception is repeatedly extended, surface that pattern as evidence that the standard workflow may need redesign. Do not automatically turn frequency into permission.

Separate emergency access from ordinary exceptions#

Some products need a way to act during an outage or urgent incident. That should not be conflated with a routine override. Emergency access may require stronger identity checks, narrower scope, immediate logging, and review after the event.

The product can still make it usable: state what the emergency action changes, who will be notified, and what recovery or review follows. A vague “break glass” control provides power without making its consequences clear.

For ordinary exceptions, the default path should remain easy to understand and auditable. For genuine emergencies, the path can be fast while leaving a clear record. Both need boundaries; urgency is not a reason to erase them.

Review the exception queue#

A practical weekly review does not need a complex dashboard. Start with a list of active overrides sorted by expiry, showing owner, scope, reason, age, and next action. Then ask three questions:

1. Is the exception still needed for the stated reason?
2. Is its scope still the smallest useful scope?
3. Should the standard workflow change, or should this exception end?

The queue also reveals missing ownership. If nobody can decide whether an exception should continue, assign a responsible role before adding more overrides. Otherwise the system has created a permanent policy with no explicit approval.

My design rule: every override needs a named owner, a bounded scope, a reason that can be reviewed, an expiry, and a safe return state. If one of those is missing, it is not a controlled exception; it is an undocumented change to how the product works.

Permission is a product decision#

A single “autonomous” toggle hides several distinct capabilities. Reading a record, drafting a reply, sending that reply, and changing an account are not equivalent just because they appear in one workflow. Their consequences differ, and so should the permission model.

I would start by describing each action along three dimensions:

• Impact: How much harm or disruption could a mistake cause?
• Reversibility: Can the action be undone completely and cheaply?
• Evidence: Can a person or system inspect why the agent chose it?

These dimensions are not a scoring formula that magically determines policy. They are prompts for a product decision. A low-impact, reversible action with clear evidence may be a reasonable candidate for automatic execution. A high-impact action that is difficult to reverse should require explicit authorization, even when the agent’s confidence is high.

For example, in a hypothetical support workflow, categorizing a message could be automatic. Drafting a response could be automatic but remain unsent. Sending a response might require approval when it contains a commitment or handles a sensitive case. Issuing a refund could be restricted to an authorized person. The important distinction is not “AI versus human.” It is what the action does and what recourse exists if it is wrong.

Use a ladder, not a toggle#

A practical permission gradient might have four levels:

This ladder is a starting point, not a universal taxonomy. Some “reversible” actions are expensive to repair; some seemingly minor actions expose private information. The product team should classify the actual domain action, not trust a label such as update or send to explain its risk.

The levels should also be assigned per action, not per agent. A workflow may allow an agent to organize files while requiring approval before sharing them. If the user has to grant broad access to get one useful capability, the product is asking them to accept unnecessary risk.

Make confirmation informative#

A confirmation dialog that says “Allow agent to continue?” transfers the decision to the user without giving them enough information to make it. A useful approval request should answer four questions:

1. What will happen? Name the action in ordinary language.
2. To what or whom? Identify the target and affected parties.
3. Why now? Show the relevant evidence or condition that triggered it.
4. What happens after approval? State whether the action is reversible and how to recover.

Imagine a proposed change to a customer record. “Update record” is not enough. The request should identify the field, old and proposed values, the source of the proposed value, and whether the change can be undone. If the agent cannot show its source, that is a reason to ask for more review, not a reason to produce a more confident-sounding prompt.

Approval should be scoped as narrowly as possible. Approving one named action should not silently authorize similar future actions. If repeated approvals become burdensome, the product can offer a bounded rule: for example, permit a defined action for a specified set of records, within a limit, for a stated period. The user should be able to inspect and revoke that rule.

Treat automation as something earned#

A common design mistake is to begin with broad autonomy and add confirmation after users discover failures. A safer sequence is to start with observation and preparation, then expand authority only when the action boundary and recovery path are understood.

That does not mean every action needs a human in the loop forever. It means each step up the ladder should answer a concrete question. What failure could occur? Who would notice? How quickly? Can it be reversed? What evidence would tell us that the action is safe enough to automate in this context?

A product team can write a short policy for each action:

Action: [specific operation]
Automatic when: [bounded conditions]
Approval required when: [risk or uncertainty]
Evidence shown: [inputs and rationale]
Recovery: [undo, escalation, or remediation]

For instance, a team might permit automatic categorization only when the record is in a defined queue, keep proposed edits as drafts, and require an authorized person to approve an external commitment. The policy is specific enough to test and revise. “The agent can handle routine cases” is not: different people will disagree about what routine means.

Measure the boundary, not just task completion#

If a workflow reports only whether the agent completed its task, it may reward unsafe behavior. A more useful review asks whether the agent stayed within its authority, whether approval requests were necessary and understandable, and whether a person could recover from a mistaken action.

For a sample of actions, inspect:

• Was the action permitted under the policy in force?
• Did the agent present the evidence needed to justify it?
• Did it stop when a condition was outside its authority?
• Could the affected user identify and reverse an error?

These are review questions, not claims that one metric can prove safety. A team can use them to find vague policies, missing controls, and approval steps that have become rote clicks. If people repeatedly approve without reading, the response should not automatically be to remove the check; first determine whether the request is poorly designed or the action is genuinely low-risk and can be bounded more tightly.

The decision rule I would take into a design review is simple: grant the least authority that still makes the workflow useful, and make every increase in authority conditional on a clear boundary, inspectable evidence, and a credible recovery path. If any one of those is missing, keep the action at the draft or approval stage.

Analysis is not the decision#

Consider a prompt about improving activation for a service with a multi-step sign-up. A candidate might map the funnel, segment users, propose research and brainstorm changes. All useful. But if the answer never picks a first move, it is an inventory of product activities rather than a product decision.

A bet is not a guess dressed up as certainty. It is a provisional choice among plausible actions. It says: given what I know now, I would spend the next unit of effort here, because this outcome matters more than the alternatives.

I use a simple sentence to force the choice:

I would do X for Y because Z; I would change course if W.

For the activation example: “I would first investigate the step where users must provide information they may not have readily available, because that could create avoidable abandonment; I would change course if the largest loss is actually before users reach that step.” This is deliberately a hypothesis, not a claim about real funnel data. The answer makes a direction legible while admitting what is unknown.

Make the trade-off inspectable#

A recommendation becomes useful when the alternative is visible. “I’d simplify sign-up” sounds agreeable until we ask what gets delayed or put at risk. Perhaps the team could instead improve the explanation of why a field is needed, or move a field later. Each option has a different cost and a different failure mode.

A compact decision note helps:

The table does not prove which option wins. It makes the decision criteria explicit. In an interview, I would select one based on the prompt’s constraints, then say what fact would reverse that selection. If the interviewer supplies new information, I can update the bet rather than defend the first answer as if it were a fixed identity.

This is also a better way to handle missing data. Instead of inventing a metric, say what you would want to know and how the answer would affect the choice. “If most abandonment occurs before this field appears, removing it is unlikely to address the main problem” is a valid conditional. “This change will improve conversion by 20%” is not valid unless the prompt provides evidence for that estimate.

Separate the bet from the test#

Candidates often jump from recommendation to a grand experiment. But a test should answer the uncertainty that matters to the decision, not merely produce a dashboard.

Write the chain in four parts:

1. Decision: What will we do if the current belief is right?
2. Uncertainty: What could make that decision wrong?
3. Evidence: What observation would distinguish the possibilities?
4. Next action: What will we do for each plausible result?

For the sign-up example, the uncertainty might be whether the field itself creates friction or whether users do not understand its purpose. A small usability session could reveal confusion, while a controlled product change might be needed to estimate behavioral impact. Those methods answer different questions; neither should be promised as a universal solution.

The fourth part matters most. If both outcomes lead to the same action, the test may be interesting but not decision-relevant. State the branches before collecting evidence: if users cannot explain the field’s purpose, improve the explanation; if they understand it but lack the information, explore deferral or an alternative input. The branches need not be perfect. They need to show that learning will affect what happens next.

Show how the bet changes#

A strong answer is not a performance of confidence. It is a small demonstration of how you reason when evidence changes. When an interviewer adds a constraint, acknowledge its effect on the choice directly: “That changes my priority. I would no longer remove the field first; I would look for a way to reduce effort without losing the required information.”

This keeps the conversation collaborative. It also prevents a common failure mode: continuing to elaborate the original plan after the premise that supported it has disappeared.

One useful self-check is to remove the analysis and read only the recommendation, its reason and its reversal condition. Can someone tell what you would do next? Can they tell what you are uncertain about? If not, the answer may be comprehensive without being decisive.

A closing check before you answer#

Before finishing a product case or behavioral example, ask yourself:

• What is my actual choice—not just the categories I considered?
• What am I giving up by choosing it?
• Which assumption carries the decision?
• What evidence would change my mind?
• What would I do under each likely result?

A useful interview answer does not need false precision or a perfect forecast. It needs a defensible first move and an honest account of how you would learn. Make the bet explicit, then make its escape hatch explicit too.

I treat this as a contract problem. Before specifying screens or prompts, write down what states mean, who may move between them, and what evidence makes a transition valid. This is useful anywhere an AI feature hands work between a model, a person, and ordinary software.

Start with user-visible states#

A common mistake is to copy internal implementation steps into the product vocabulary. “Prompt sent,” “tool returned,” and “response parsed” may help an engineer debug, but they rarely tell a user what they can do next.

Instead, list the states that change the user’s choices. A document assistant might have:

This is a product model, not a claim that every system needs these exact labels. The test is practical: can a user infer whether the system is waiting, asking, finished, or unable to proceed?

Keep hidden technical detail out of the state list unless it changes a user decision. A retry counter might be operationally important without needing its own user-facing state. Conversely, “waiting for approval” deserves a distinct state if the user must act before anything else can happen.

Specify transitions, not just destinations#

A state diagram without transition rules is decoration. For each move, specify the trigger, the actor, and the evidence that permits it.

For example:

• Draft → Processing: a user submits; the system records the submitted input.
• Processing → Review required: the model returns a proposal that passes basic structural checks.
• Review required → Applied: an authorized person accepts the proposal and the target system confirms the change.
• Processing → Blocked: a required dependency fails or the workflow reaches a defined limit.

The distinction between a proposal and an applied change matters. A model returning plausible text is not proof that a record was updated. Likewise, a button click is not proof that the server accepted the action. The transition should depend on the authoritative event, not whichever component reports success first.

A useful specification row is: from state; trigger; authorized actor; validation; resulting state; user-visible evidence; recovery path. Fill one row for each transition that changes a user’s options. If two transitions have different permissions or consequences, they are not the same transition just because they end in the same state.

Decide who owns the truth#

Distributed workflows often have several versions of “current”: the model’s conversation, a browser view, an application record, and a queued job. If those disagree, the product needs a rule for which one wins.

Write the rule in plain language. For instance: “The application record is authoritative for whether a change was applied; the model’s response is only a proposal.” Then specify what the interface does when the record cannot be checked. It should not quietly display “Applied” based only on the model’s assertion.

This also clarifies what counts as evidence. A transition might require a saved record identifier, a confirmed status from the destination service, or a human approval event. Avoid vague conditions like “when the task succeeds.” Success must name an observable signal and its source.

For asynchronous work, include timestamps or freshness cues where stale information could mislead. A status read five minutes ago may be accurate enough for a long-running report and dangerously stale for a payment or permission change. The product requirement should state the acceptable freshness based on the consequence of acting on old state.

Make interruption a first-class path#

Users navigate away, networks fail, and workers restart. If the workflow has no defined behavior for interruption, users will interpret missing progress as either failure or success, often incorrectly.

For every in-progress state, answer three questions:

1. Can the work continue without the user’s session?
2. If the user returns, how is the same task found rather than duplicated?
3. If the outcome is unknown, what can the user safely do next?

Suppose a request times out after submission. The system may not know whether the downstream action completed. Offering “try again” without checking can create a duplicate. Better behavior is to show “Checking status,” use a stable task identifier to reconcile the result, and only offer a retry when the original action is known not to have applied—or when the action is safe to repeat.

Not every product needs sophisticated recovery. A one-off draft generator may simply let the user restart. But that should be a deliberate decision based on the cost of duplicated work and lost progress, not an accidental consequence of the implementation.

Put the contract in the acceptance criteria#

A state contract becomes useful when it changes what the team tests. For each transition, define at least one normal case and one case where the expected evidence is missing or contradictory.

A compact acceptance checklist:

• The visible label matches the authoritative state.
• Only permitted actors can trigger the transition.
• A transition is not shown as complete before its evidence arrives.
• Refreshing or reopening the workflow does not invent a new state.
• A timeout or partial failure leaves a safe next action.
• Repeating an action cannot silently duplicate a consequential change.

These are not all model-quality tests. They are workflow tests around the model. That distinction helps teams avoid treating every inconsistency as a prompt problem when the real gap is ownership, persistence, or permissions.

The next time a feature crosses a model boundary, ask in review: What is the source of truth for each state, and what evidence authorizes the next transition? If the answer is unclear, the workflow is not ready for a polished status badge.

Make the alternative explicit#

A launch narrative tends to move in one direction: problem, solution, result. That structure hides the choice. If the case study never names a credible alternative, the selected path can look inevitable rather than reasoned.

Write one sentence before describing the solution: “We could have _, but chose _ because ____.” The alternative should be something a competent team might actually do, not a straw man.

For example, imagine a workflow where users repeatedly submit incomplete requests. The options might be to add more required fields up front, or let people submit quickly and route missing details to a follow-up queue. Neither is universally right. The trade-off is between preventing incomplete work at entry and preserving a low-friction start while accepting operational follow-up.

State what the alternative predicts#

A counterfactual is useful when it makes a prediction. “The longer form would reduce missing information” is testable; “the longer form would be worse” is not.

Use a compact comparison:

The table does not need invented results. If the work was not measured, label the evidence as a hypothesis or an instrumentation gap. Clear uncertainty is more credible than a precise-looking number without a trustworthy source.

Show why the decision changed#

The strongest case studies show how evidence moved the team from one option to another. Say what you knew at the decision point, what remained unknown, and what observation would have caused you to reverse the choice.

A useful template:

We chose A over B because [evidence or constraint]. We accepted [specific cost]. If [observable signal] crosses [threshold or condition], we will revisit the choice.

If no threshold existed, say what review point or qualitative trigger the team used. Do not retrofit certainty after the outcome is known. Separate the original reasoning from what you learned later.

Keep the claim proportional#

A case study should not claim that a decision caused an outcome when several changes happened together. It can still be useful: describe the decision, the evidence available, the observed result, and the limits on attribution.

Before publishing, ask: What was the real alternative? What did each option predict? What cost did the chosen path accept? What evidence could have changed my mind? If those answers fit in a few sentences, the reader can evaluate your judgment—not just admire the screenshots.

That split creates two different promises. API users can begin testing an early preview through the hosted service. People waiting for weights have to wait for another milestone. The announcement also says Mistral is using the preview period for real-world red-teaming with selected partners and authorities before the weights release.

The useful question is who can learn now#

A staged launch can be a sensible way to collect feedback and reduce risk. But “available” needs a noun after it. Available to whom, through which interface, under what limits, and with what production expectations?

A PM evaluating a model release should separate three things: access to a preview, evidence about performance on the intended workload, and permission to build a dependable product around it. A preview can help answer the first technical questions. It does not automatically answer the other two.

For the user, the key contract is what can be tried now and what remains promised for later. For the team, the key decision is whether the preview is enough to start an experiment or whether the missing weights are a dependency. Those are different launch outcomes and should not be collapsed into one headline.

Make the milestone testable#

The announcement gives a timing expectation for the weights, not a substitute for the evaluation a product team needs. Before adopting any preview, write down the workload, the failure cases, the access mode, and the point at which you will decide to continue or wait.

The teardown rule: treat staged availability as separate product states. Evaluate each one on what it lets your users and team do today, not on what the next milestone may unlock.

Explainability is a user task#

“Explain the model” is too broad to guide a product decision. A user usually has a narrower question: Which document supports this claim? What changed between the source and the summary? What assumption drove this recommendation? Can I correct the input?

The interface should answer the task, not offer a vague promise of transparency. Consider a tool that summarizes a policy and flags a possible exception. A useful result might show:

• Source: the exact passage and document date.
• Interpretation: the condition the system believes the passage expresses.
• Application: why the current case appears to match or differ.
• Next step: inspect the cited section, provide missing context, or route for review.

These parts should not collapse into one confident paragraph. A quoted passage is evidence; the interpretation is a transformation; the recommendation is a decision aid. Keeping them distinct lets the user challenge the right layer.

Put evidence beside the claim#

A source link at the bottom of a long response is technically available but often practically disconnected. The user has to guess which source supports which sentence, then reconstruct the reasoning themselves.

Instead, attach evidence at the smallest useful unit. In a generated summary, each material claim can open its supporting passage. In a classification result, show the input fields that influenced the category. In a draft, mark which sentences are extracted facts and which are proposed language.

This does not mean exposing every internal step or dumping a chain of thought. The product needs to present verifiable inputs and outputs, not private reasoning traces. Evidence should be selected for user inspection: source locations, relevant values, timestamps, and transformations that can be checked.

A practical design test is to hide the main answer and ask a reviewer to find the support for one claim. If the reviewer cannot do that without searching the entire source set, the evidence is not close enough to the decision.

Show the transformation, not just the citation#

A citation can be correct while the conclusion is wrong. The source may say that a condition applies only after a date; the summary may omit the date. The document may describe a proposed rule, while the interface presents it as active. A matching phrase may be irrelevant to the user’s specific case.

So show the transformation in a compact form. For example:

The table is not a demand to reveal model internals. It is a way to let the user inspect the product’s observable reasoning: what information was used, what rule was applied, and what conclusion followed.

When a result depends on a missing field, say so directly. “Needs review” is less useful than “The effective date is absent; check the original record before applying this rule.” The latter makes uncertainty actionable.

Design for correction#

Inspection without correction can become theater. If users can spot an error but cannot fix its input or route it to someone who can, the interface has exposed a problem without providing a safe path forward.

For each kind of evidence, define an appropriate correction:

• Wrong source: remove it or select the correct record.
• Wrong extracted value: edit the value or mark it as unavailable.
• Wrong interpretation: choose the correct condition or request review.
• Incomplete context: add the missing information before rerunning.

Keep these edits explicit. A user changing an extracted value should be able to see whether the final result updates, and whether the correction is local to this case or changes a reusable source record. Those are different permissions and consequences.

A useful design exercise is to write one error-recovery path for each visible evidence element. If a cited passage is outdated, what can the user do? If a field was misread, what changes downstream? If the system cannot decide, who receives the case and what information arrives with it?

Match confidence language to evidence#

A percentage can look precise without telling a user what to do. Unless the number is calibrated for the relevant task and population, “92% confident” may communicate more certainty than the product can justify.

Prefer confidence language tied to observable conditions: “Two required fields are present,” “The source documents disagree,” or “No supporting passage was found.” These statements point to the basis of the result and can be checked. If a score is needed for ranking, explain what it measures and avoid presenting it as a probability unless that interpretation is warranted.

The same principle applies to visual hierarchy. Do not style an unverified suggestion like a completed action. A recommendation awaiting confirmation should look and behave differently from a transaction that has been confirmed by the destination system.

A review checklist for the interface#

Before shipping an AI-generated answer that could change a user’s decision, test it with a reviewer who did not build the feature. Give them a realistic example and ask them to locate the evidence, identify what the system inferred, correct a wrong input, and explain what remains uncertain.

Use this checklist:

1. Can the user connect each important claim to its supporting source?
2. Can they distinguish source facts from system interpretation?
3. Can they identify missing, conflicting, or stale information?
4. Is there a safe correction or escalation path?
5. Does the interface distinguish a suggestion from a confirmed outcome?

If the reviewer cannot answer those questions, adding a longer explanation probably will not fix the core problem. Change the interaction so the evidence is inspectable and the next action is clear. Trust should be earned at the point where the user needs to decide.

A timeout is not an outcome#

A tool call has at least two separate events: the system receives a request, and the agent receives a response. A timeout tells us the second event did not happen in time. It does not tell us whether the first event caused a change.

This distinction matters whenever a tool can create an external side effect: sending a message, issuing a refund, submitting a form, changing access, or reserving a resource. The agent’s conversational context may say “I tried,” but that is not evidence about the external system.

Start by classifying each action in a workflow:

“Idempotent” needs to describe the actual tool behavior, not the intention in the prompt. Setting a field to “approved” may be repeatable; calling “approve next item” may approve a different item on the second attempt. Ask what the external system does when it receives the same request twice.

Give each action a durable identity#

For every consequential action, create an action record before calling the tool. It should have a stable identifier that survives model retries, plus enough context to reconcile the call without storing unnecessary sensitive data.

A minimal ledger entry could contain:

• Action ID: a unique identifier for this intended operation.
• Intent: the specific change requested, in a compact and inspectable form.
• Target: the external record or resource, if known.
• Status: prepared, submitted, confirmed, failed, or needs reconciliation.
• Attempt details: timestamps, tool response identifiers, and error category.
• Recovery rule: what the system may safely do next.

The key is to persist the action ID before sending the request. If the process crashes after the external action but before updating its own state, the record still tells the recovery path that an operation may be in flight.

Where the external service supports an idempotency key, pass the same action ID on each retry of the same intended operation. Do not generate a fresh key just because the previous response was missing; that would turn a retry into a new operation. If the service has no idempotency support, use a lookup or reconciliation step before attempting another write.

A ledger is not a transcript of the agent’s reasoning. It is a state machine for side effects. Keep it small enough that software can enforce it and an operator can understand it during an incident.

Separate intent from execution#

A useful state model distinguishes what the agent decided from what the external system confirmed. One practical sequence is:

1. Prepared: the action and its authorization are recorded, but no request has been sent.
2. Submitted: the request was sent; the outcome may still be unknown.
3. Confirmed: a response or subsequent lookup proves the intended result exists.
4. Failed: the system has evidence the action did not happen and will not complete later.
5. Needs reconciliation: the outcome is ambiguous or the system cannot safely decide.

Avoid treating a caught exception as equivalent to “failed.” A connection reset after submission is ambiguous; a validation error returned before execution may be a definite failure. The tool adapter should classify errors according to its contract, not ask the language model to guess from an arbitrary message.

The agent’s user-facing language should follow the same distinction. If the action is merely submitted, say it is being checked. Do not claim success until there is confirmation. If the result is unknown, explain that clearly and avoid inviting the user to repeat the request before reconciliation.

Make retries a policy, not a reflex#

Retry logic should be attached to the action type and error category. A generic “retry three times” wrapper can multiply side effects while appearing robust.

A decision rule can be simple:

• If the operation is read-only and the error is transient, retry with a bounded delay.
• If the operation is idempotent and uses the same key, retry that same operation.
• If the operation is non-idempotent and the outcome is unknown, query by action ID or target before any new write.
• If reconciliation cannot establish the outcome, mark it for a person rather than guessing.
• If the error is a permission or validation failure, do not retry unchanged; surface the missing prerequisite or correct the input.

Set a maximum retry window as well as a count. A request that remains ambiguous after the useful recovery period should leave the automated path and enter a visible queue. Otherwise, retries can continue long after the user has moved on, or a backlog can quietly accumulate.

For example, suppose an agent submits a support ticket through a tool that has no idempotency key. The request times out. The recovery worker searches for a ticket matching the action’s external reference. If exactly one match exists, it marks the action confirmed. If none exists and the service can guarantee the earlier request is no longer processing, it may submit once more. If there are multiple matches or the search is inconclusive, it routes the record for review. The rule is explicit about what the system knows and what it does not.

Design reconciliation before launch#

A ledger only helps if the system can use it to resolve uncertainty. During design, answer these questions for every external write:

• Can the destination accept an idempotency key or client-generated reference?
• Can the system query for the result using that reference?
• How long can a request remain in progress after the caller times out?
• Who owns unresolved actions, and where do they see them?
• What should the user see while the result is unknown?
• How can an operator safely retry, cancel, or mark the action resolved?

Test the failure sequence, not only the happy path. Simulate a timeout before the request reaches the service, after the service commits but before its response returns, and while the destination is still processing. The expected result should be different where the evidence differs: no action to reconcile, a completed action to recognize, or an in-flight action to wait on.

Track operational signals that reveal whether the design is working: actions in the needs-reconciliation state, their age, duplicate effects found, and manual resolutions. These are not interchangeable with model-quality scores. They tell you whether the product can account for its side effects.

Before an agent can perform a consequential write, complete this checklist: stable action ID; persisted intent; known idempotency behavior; timeout classification; reconciliation query; bounded retry rule; owner for unresolved outcomes. If any item is missing, keep the action behind a human confirmation step until the recovery path exists.

A pass rate is not a risk statement#

Suppose an assistant answers questions from a support knowledge base. An eval has 100 examples: 80 ordinary questions, 15 questions with incomplete information, and 5 where the correct response is to refuse or ask for clarification. A model that passes all ordinary questions and fails all five refusal cases posts a 95% pass rate. That number says little about whether the assistant is safe to expose to users.

The denominator is doing too much work. Each example counts equally, but examples differ in consequence and frequency. Worse, the eval designer may have included many variations of the easy cases because they were simple to write. The resulting score measures the shape of the test set as much as product quality.

A failure budget makes the hidden trade-off visible. Instead of one threshold, define limits by failure class. For example:

These are illustrative limits, not universal benchmarks. The important move is to make the threshold a product decision before looking at the result.

Define failures in terms users experience#

A taxonomy should describe what went wrong for the user, not only which model component may have caused it. “Retrieval failure” is useful to engineers, but it does not tell a PM what to count. “The assistant gave a specific answer despite having no supporting source” is observable and actionable.

For each class, write three things:

1. Observable condition: What would a reviewer mark as a failure? Avoid labels such as “bad answer.”
2. User consequence: What happens next if this failure reaches production? Can the user notice, correct, or reverse it?
3. Exposure: How often is the triggering situation likely to occur in the real workflow?

Consider a generated summary that omits a qualification. A generic omission might be minor when a user can inspect the original document. The same omission could be critical if the summary is used as the only input to a later decision. The output text alone may be identical; the workflow context changes the consequence.

A practical annotation rule could say: “Mark unsupported certainty when the answer asserts a fact absent from the provided sources, without signalling uncertainty or asking for the missing information.” Two reviewers can apply that rule more consistently than “mark hallucinations.” Include counterexamples: a concise answer that leaves out irrelevant detail should not fail merely because it is not exhaustive.

Set limits using consequence and exposure#

A failure budget is not just a severity ranking. A rare catastrophic failure and a frequent recoverable error require different controls. Start with a simple risk sketch for each failure class:

• Severity: What is the worst plausible user consequence?
• Exposure: How often does the relevant situation appear?
• Recoverability: Can the user detect and undo the result before harm?

This need not pretend to be precise math. A low/medium/high rating is often more honest than multiplying made-up numbers into a risk score. Use the ratings to decide whether a class needs a zero-tolerance gate, a maximum count, or monitoring after launch.

For instance, unsupported certainty in a high-consequence workflow might have a zero-failure release limit on a targeted challenge set. A stylistic mismatch in a low-stakes draft assistant might be tracked as a trend rather than a blocker. The test size also matters: “zero failures” across five examples is weak evidence. State the number and type of examples next to the limit, then expand the set as you observe real cases.

Do not silently change the limit when the model misses it. If a release is still justified, record who accepts the exception, the affected workflow, the temporary mitigation, and when the decision expires. Otherwise a budget is just a dashboard decoration.

Make every limit lead to an action#

A threshold without an owner creates debate at the worst time: after a release candidate has failed. For each failure class, decide in advance what happens when the limit is exceeded.

A compact release table can include:

The action can depend on the cause. If a failure appears only when source material is absent, a product-level clarification step may be more effective than prompt tuning. If the model ignores a clear source, retrieval or generation may need investigation. The taxonomy should support diagnosis without assuming the cause in advance.

This also separates two questions teams often collapse: “Did the system get better?” and “Is it safe enough for this workflow?” A model may improve on average while still exceeding a critical failure limit. Conversely, a small regression in a low-consequence class may be acceptable if a major user risk has been reduced. The budget preserves both facts instead of squeezing them into one score.

Keep the budget alive after launch#

Offline examples are a sample, not a complete map of production. When users correct an answer, abandon a flow, or ask for a human, those events can reveal missing failure classes. Review a small, privacy-appropriate sample of these signals regularly and turn confirmed patterns into eval cases.

Do not add every odd output as a new test. First ask whether it represents a distinct user-visible failure, whether the existing taxonomy already covers it, and what decision the test would change. A test that has no plausible effect on a release or product decision adds maintenance without adding control.

On Monday, take your current eval and write down its three most consequential failure classes. For each one, name the observable failure, the test slice and denominator, the release limit, and the person who owns the next action. If you cannot fill those in, the headline score is not yet a release criterion.

Separate the evidence from the belief#

A product bet usually mixes three things: an observed problem, an explanation for it, and a proposed response. They deserve separate lines because each has a different confidence level.

Consider a hypothetical scheduling tool. A team sees that people abandon a booking form. That is an observation, assuming the event is measured correctly. “They abandon because the form asks for too much detail” is an explanation. “A shorter form will increase completed bookings without creating costly follow-up” is a bet.

Those statements can all be plausible while only the first is directly evidenced. If a roadmap discussion jumps from abandonment to shorter form, it quietly treats the explanation as fact and the outcome as guaranteed.

Write the chain explicitly:

• Observed: What did we see, and where did the evidence come from?
• Believed: What explanation are we using?
• Bet: What change do we expect to improve, for whom?
• Risk: What else might happen if the belief is wrong?

The purpose is not to make a proposal sound cautious. It is to locate the uncertainty that could invalidate the work. A team can then debate the actual belief rather than arguing about a feature as if it were the only possible response.

Write the disconfirming observation#

“Validate the idea” is too vague to guide a test. Ask instead: what could we observe that would make us change the plan?

For the shorter booking form, one disconfirming observation might be that people who abandon do so before reaching the long section. Another might be that users complete a short version but then require enough follow-up that the total task becomes harder. These observations point in different directions: the first challenges the diagnosis; the second challenges the proposed trade-off.

A useful statement has four parts:

If we observe [specific evidence] in [defined context], we will [change, pause or stop] because it weakens [assumption].

For example: “If people who leave the current form mostly exit before seeing the detailed questions, we will not build a shorter-form project around those questions as the primary cause.” That does not prove what the cause is. It prevents the team from treating one untested explanation as settled.

Make the threshold concrete enough that two people would interpret the result similarly. “Users dislike it” is not a threshold. “In five moderated sessions, at least four participants reach the same point of confusion without prompting” is more observable, though it is still a small qualitative signal, not a population estimate. The method and the claim must stay proportional to each other.

Test the uncertainty, not the solution polish#

When the risky assumption concerns the cause of a problem, a polished prototype may answer the wrong question. It can show that someone can use the proposed interface while telling you little about why the existing behavior occurs.

Start with the least expensive test that can distinguish between plausible explanations. Depending on the question, that could be:

• Inspecting a small, clearly defined sample of session replays or support cases, if they are available and appropriate to use.
• Asking users to complete the current task while narrating what they expect at the point of hesitation.
• Showing a low-fidelity alternative only after understanding the current behavior.
• Running a manual concierge version of the proposed change, with a clear record of what was done by a person.

A small sample is useful for finding a mechanism or a surprising failure. It does not establish prevalence. If the decision depends on how common a behavior is, plan a measurement that can answer that question rather than stretching a handful of interviews into a percentage.

Write down the test before running it: target participant or case, task, evidence to capture, stopping condition, and the decision that follows each plausible result. If every result leads to the same roadmap item, the test is not informing the decision. Either the bet is already committed for another reason, or the experiment needs a different question.

Keep the cost of being wrong in view#

Not every uncertain belief deserves an experiment. The cost of delay and the cost of a wrong bet both matter. A reversible copy change may justify a quick test; a workflow that can exclude eligible users or create substantial manual work deserves stronger evidence and a safer rollout.

Use a simple two-axis check:

This is a conversation aid, not a scoring formula. “High impact” should refer to a concrete consequence for users, operations, or the business. “Easy to reverse” should include hidden costs such as migration, retraining, or trust lost after a bad experience.

Also name the downside you will monitor. If shortening the form reduces effort but increases incomplete submissions, the primary success signal cannot be the only metric on the launch readout. A guardrail makes the trade-off visible before the team starts celebrating the number that moved.

Turn the result into a decision#

A test should end in a decision, not a slide labeled “learnings.” Before starting, write the possible outcomes and the action attached to each:

1. The explanation holds up: proceed to a bounded test of the proposed change.
2. A different cause is more plausible: revise the problem framing and test that cause.
3. Evidence is mixed or too weak: reduce the scope, gather a more discriminating signal, or defer the bet.
4. The downside appears: stop or add a control before expanding.

Keep the record short: the original assumption, evidence collected, limitation, decision, and owner of the next step. If the result changes the roadmap, preserve the reason alongside the change. That helps the team avoid repeating the same debate later, and gives future reviewers a fair account of what was knowable at the time.

Before you commit a roadmap bet, ask: what specific observation would make us change our mind, what is the smallest credible way to look for it, and what will we do if we find it?

Choose a decision that had real alternatives#

Start by naming a decision, not the project. “We built an onboarding flow” describes activity. “We chose to let an operator review incomplete applications rather than reject them automatically” gives the reader something to assess.

A useful test: can you name at least two plausible options that were considered? If not, the case may be a feature description rather than a product decision. The alternatives need not be elaborate. They might be ship now versus wait for more evidence, automate versus keep a human checkpoint, or solve the common path versus handle an exception first.

Use a compact opening card:

• Decision: What choice needed to be made?
• Constraint: What made the choice difficult (time, risk, data, dependencies, or user behavior)?
• My role: Which parts did I own, influence, or support?
• Outcome: What changed, and how do I know?

For example, a hypothetical case might say: “We needed to decide whether to launch an automated document check or first improve the manual review queue. I owned the problem framing and workflow proposal; engineering and operations shaped feasibility. The available evidence was a small set of observed review cases, not a representative sample.” That is more informative than a long introduction to the company or product.

Be precise about responsibility. “I led” can mean anything from setting the direction to coordinating a meeting. Name the work: framed the problem, compared options, wrote acceptance criteria, designed the evaluation, or aligned the launch gate. A collaborative result does not become less impressive when the reader can tell who contributed what.

Show what you knew when you chose#

A decision trail is strongest when it separates what was known then from what became clear later. Otherwise, a successful outcome can make an uncertain decision look obvious in retrospect.

Include the evidence that actually informed the choice: user interviews, support themes, workflow observations, a prototype test, operational records, or an evaluation set. State its limits in the same breath. “We reviewed 18 cases” is not a claim about all users; it tells a reader what the sample was. If the evidence was qualitative, say what pattern it suggested and what it could not establish.

A simple evidence block is enough:

Use real details only when you can substantiate them and are permitted to share them. If confidentiality prevents naming a client or showing data, describe the structure of the problem at a safe level. Do not replace missing evidence with an invented metric. A clear limitation is a sign of judgment, not a weakness in the case.

Make the trade-off visible#

The reader needs to see why the chosen option beat the alternatives. Put the options side by side and make the deciding criterion explicit. A paragraph can do this, but a small comparison is often faster to scan:

This is a hypothetical illustration, not a universal recommendation. In a different setting, the costs may reverse. The point is to expose the criterion: safety, time-to-learn, reversibility, customer effort, or operational capacity.

Also include the cost of the option you chose. Every product decision leaves something undone. If you chose a narrow launch, say what capability remained out of scope. If you chose speed, say which uncertainty you accepted and how you planned to watch it. A case that only lists benefits reads like a pitch; a case that names the compromise reads like product work.

Connect the artifact to the decision#

Screens and diagrams are useful when they answer a question. Show the old and proposed workflow if the decision changed the sequence of work. Annotate the interface where a status, prompt, or fallback embodies the trade-off. Include a short excerpt of a spec or evaluation rubric if that artifact makes the reasoning concrete.

For each visual, add a caption with three parts: what the reader is seeing, what decision it represents, and what changed because of it. Avoid decorative device mockups that enlarge a screenshot without adding context. One annotated diagram can explain more than six screens in a carousel.

When the work cannot be shown, use a redacted or reconstructed artifact and label it honestly. Never imply that synthetic examples are production data. The purpose is to make the decision inspectable while respecting the boundaries around the underlying work.

Close the loop without overclaiming#

End with the outcome and the next decision it enabled. Use a measured result if you have one, along with its denominator and time window. If measurement was unavailable, report the observable operational change and say what remained unmeasured. “The team shipped the workflow” is an output, not proof that the user problem improved.

Separate three things that portfolios often blur:

1. Delivery: What was released or changed?
2. Effect: What user or business outcome was observed, and by what measure?
3. Learning: What would you change now, given what happened or what you later learned?

Do not claim causality from a before-and-after number unless the evidence supports it. If other changes happened at the same time, describe the result as an observed movement, not an effect caused solely by your work. If the launch was too recent to judge, say so and name the signal you would monitor next.

A useful final paragraph is often short: “We released the narrower review aid. It made the missing-context decision visible, but we did not yet have enough evidence to claim that it reduced total handling time. The next decision was whether to expand coverage after observing the exception types.” This gives the reader an outcome, a limit and a credible next step.

Use the same trail in every case#

A portfolio does not need a new storytelling format for every project. Repeating a decision structure helps reviewers compare how you work across different problem spaces. Keep the case concise enough to scan, then provide detail where the evidence or trade-off deserves it.

Before publishing a case, check:

• Is the central decision clear in the first few lines?
• Are at least two plausible options visible?
• Can a reader distinguish my contribution from the team’s work?
• Does each claim match evidence I can share?
• Is the trade-off and the option not chosen explicit?
• Does each screenshot or diagram explain a decision?
• Are delivery, measured effect and learning kept separate?
• Have I removed confidential names, data and identifying details?

If a reviewer can trace what you knew, what you chose, what you gave up and what happened next, the portfolio is doing more than displaying finished work. It is showing how you make decisions when the answer is not yet obvious.

Start with the user-level harm#

“Wrong answer” is too broad to guide a product decision. A spelling mistake in a generated draft and a fabricated eligibility reason may both count as incorrect outputs, but the cost and recovery path are different.

Write down a small set of outcome classes before selecting a metric. For a hypothetical assistant that drafts replies to customer messages, the classes might be:

This is not a universal taxonomy. It is a prompt to describe failures in terms of what a user experiences and what the product must do next. Keep the categories few enough that a reviewer can classify a test case without a debate.

Give each class its own boundary#

A single “acceptable error rate” hides the distribution of risk. If harmless style defects dominate a test set, the overall score can look strong while a rarer but consequential failure remains invisible.

For each outcome class, set a boundary in plain language. For instance: “A draft may need stylistic edits, but it must not invent a policy or send without a human confirmation.” If you have enough representative examples to quantify the boundary, record the denominator and the threshold. If you do not, say that the evidence is insufficient; do not manufacture a percentage to make the brief look precise.

A useful planning table has four fields:

1. Failure class: the observable user-level mistake.
2. Exposure: where in the workflow it can reach a person or trigger an action.
3. Limit: what frequency or severity is tolerable for this release, supported by evidence where possible.
4. Containment: what prevents further impact once the limit is crossed.

“Improve accuracy” belongs nowhere in that table. It is an intention, not an operating boundary.

Make the denominator match the decision#

A model score is meaningful only when the test examples represent the product decision. For a drafting feature, counting every generated sentence as an observation can obscure the more useful unit: a draft that a user might send. For a triage feature, the consequential unit may be a case routed to the wrong queue.

Write the denominator beside every proposed threshold. “No more than two unsupported claims per hundred evaluated drafts” is interpretable only if the drafts cover the relevant customer intents, policy exceptions, and incomplete inputs. A hundred near-identical happy-path prompts do not provide that evidence.

Separate severity from frequency as well. A low-frequency event can still be unacceptable if its impact is severe. In that case, the release boundary may be categorical: the feature cannot take the consequential action autonomously, regardless of its average score. That can be a more defensible product decision than trying to justify a tiny numerical allowance from a small test set.

Treat the budget as something that can be spent#

An error budget is useful only if a team knows what consumes it. Decide whether a failure counts when it appears in pre-release evaluation, in monitored production traffic, or both. These answer different questions: evaluation estimates readiness; production monitoring tracks what users actually encounter.

For example, a team might require zero observed unsupported policy claims in a defined set of high-risk test scenarios before enabling automatic sending. In production, it could track user-reported or reviewer-confirmed incidents separately, with a pause condition if any such incident occurs. The exact gate depends on the product’s consequences and evidence; the important point is to define the event and response before launch.

Do not let a budget become a target to spend. A threshold is a ceiling for decision-making, not permission to expose users to predictable failures. If the budget is exceeded, pause the relevant capability, preserve the context needed to investigate, and assign an owner to decide whether to repair, narrow, or remove it.

Design the exhausted-budget state#

Many briefs describe only the successful path. The reliability contract must also say what happens when the system is uncertain, unavailable, or beyond its error boundary.

For the draft assistant, the exhausted-budget state could be: stop generating send-ready text, keep the original customer message visible, and offer a blank reply editor. The user still completes the task, but the product no longer presents an unsafe draft as if it were usable. That fallback should preserve the user’s progress and explain the limitation without claiming certainty about why the model failed.

Assign an operational owner too. Who reviews a flagged incident? Who can disable the capability? What signal tells them to act? A feature flag without a named responder is not a complete containment plan.

Put the contract in the brief#

Before implementation, add a compact reliability section to the product brief:

• Allowed: errors the user can safely notice and correct.
• Blocked: errors or actions that must not reach the user uncontained.
• Evidence: evaluation examples, denominator, and known gaps.
• Fallback: the usable non-AI path when confidence or service is insufficient.
• Tripwire: the event that pauses or narrows the feature.
• Owner: the person responsible for reviewing the tripwire and deciding next steps.

Then ask one question in review: If this exact failure happens tomorrow, what does the user see, and who acts? If the answer is vague, the feature’s error budget is not ready to ship.

The engineering post-mortem often points to bank downtime or third-party SDK latency. But session replays show that drop-offs rarely happen because of an API failure. They happen because product teams treat Account Aggregator (AA) as a background data pipeline rather than a high-friction consent interaction.

In India’s financial ecosystem, regulated under the Reserve Bank of India Master Directions for Account Aggregators, the AA network acts as a consent broker between Financial Information Providers (banks) and Financial Information Users (lenders or personal finance apps). The framework is architected for privacy, but privacy requires explicit user comprehension. When an interface fails to explain what is happening, who is asking, and why a second SMS just arrived, users close the app.

The dual-SIM reality breaks account discovery#

The single largest drop-off in the Account Aggregator journey occurs in the first five seconds, during account discovery. An applicant signs up for your product using their primary data SIM. But their legacy salary or savings account at a bank is tied to a secondary mobile number they have used for years.

When your client initiates discovery against the AA registry using the signup mobile number, the API returns zero discovered accounts.

Most default SDK implementations handle this scenario with a dead-end message: “No accounts found for this mobile number.” The user assumes the service is broken or their bank is unsupported, and leaves. In unoptimized funnels, this single failure mode accounts for 18% to 24% of all initiated sessions.

[ App Signup: Number A ] ──> [ AA Discovery: Number A ] ──> [ FIP Bank: 0 Accounts ] ──> Abandon

To fix this, decouple your application’s identity phone number from the bank discovery phone number. Before calling the discovery API, present an explicit confirmation prompt:

“We will look for your accounts linked to +91 98XXX XXXXX. Is your bank account registered with this number or a different SIM?”

Providing a simple “Use a different bank-linked number” input with inline SMS verification recovers more than half of these stranded sessions. It treats dual-SIM usage not as an edge case, but as the default operating reality of the Indian smartphone market.

Consent scope paranoia kills conversion#

Once accounts are discovered, the user faces the consent approval screen. This screen is governed by regulatory requirements specified by Sahamati’s operational framework, detailing the Financial Information User, data life, fetch frequency, and date range.

Too many product managers accept the default SDK consent template, which often requests recurring access for three years with daily fetch frequencies. When an applicant applying for a one-time credit check sees a legal screen stating that an external app will monitor their bank account daily until 2029, trust evaporates.

Every additional month of requested transaction history and every recurring fetch permission decreases consent completion. If your underwriting policy only scores based on the last 180 days of cash flows, request exactly 180 days.

Consent conversion is inversely proportional to the blast radius of the requested permission.

Pair this minimal scope with plain-language assurances directly above the consent trigger: confirm that consent does not permit moving money, and that consent can be revoked at any time from their Account Aggregator profile.

The two-step OTP journey needs a visual contract#

In payment workflows, Indian consumers expect a single Two-Factor Authentication (2FA) prompt. In the Account Aggregator flow, users encounter two distinct OTP steps:

1. AA Registration / Login OTP: Validates the user’s mobile number with the regulated Account Aggregator entity (such as Setu, Finvu, or Anumati).
2. Bank FIP Linking OTP: Sent directly by the user’s bank to authorize linking and data sharing for the selected account.

When users receive the first OTP, they enter it and expect immediate completion. When a second OTP prompt instantly appears on screen from a completely different SMS header (such as VK-HDFCBK instead of the AA provider), confusion sets in. Users assume the system looped or that a duplicate action is being authorized.

Include the bank’s brand mark alongside the second OTP input field. Seeing their bank’s familiar logo grounds the interaction and reassures the applicant that the incoming bank SMS is legitimate.

Set a hard latency budget and preserve state on fallback#

Financial Information Provider (FIP) APIs operate on heterogeneous banking infrastructure. While leading private banks respond to discovery and consent requests within two to three seconds, public sector banks and regional cooperative institutions can experience latency spikes exceeding 15 seconds, or suffer temporary timeouts during peak hours.

If your onboarding screen displays an indefinite spinning loader, the user will abandon the session within 10 to 12 seconds. Worse, if your frontend handles a timeout by throwing a generic error alert that resets the application form, you force the user to re-enter personal details from scratch.

Implement a strict client-side latency budget of 12 seconds for the entire AA exchange:

AA Request Initiated (0s)
   │
   ├─► Success within 12s ──► Ingestion & Parsing ──► Complete
   │
   └─► Timeout at 12s ─────► Graceful Degradation
                                │
                                ├─► Net Banking Login (Alternative)
                                └─► Direct PDF Statement Upload (Prefilled)

If the 12-second window lapses without a successful consent callback, transition the screen immediately to your secondary ingestion rail: Net Banking login or encrypted PDF statement upload. Pass forward the user’s verified mobile number, selected bank name, and application ID so the fallback screen is already pre-configured. The user experiences the fallback as an intentional, helpful alternative rather than a broken journey.

The four funnel metrics that diagnose drop-off#

Measuring Account Aggregator performance using a single top-level metric like “AA Success Rate” conceals the exact point of friction. To maintain a healthy ingestion pipeline, track four isolated ratios across your analytics pipeline:

1. Discovery Rate (Discovered Accounts / Initiated Flows): Diagnoses phone number mismatches and FIP lookup downtime. If this drops below 75%, audit your phone-number matching logic and prompt copy.
2. Account Selection Rate (Selected Accounts / Discovered Accounts): Diagnoses confusion when a user holds multiple accounts at the same institution (such as dormant joint accounts versus active salary accounts).
3. Consent Completion Rate (Verified Bank OTPs / Rendered Consent Screens): Measures user trust and OTP delivery reliability. If this drops, review consent scope duration, recurring fetch permissions, and two-step progress messaging.
4. Data Delivery Rate (Parsed Statements / Verified Consents): Measures technical reliability of the FIP data payload transfer. A drop here indicates downstream bank server latency or schema deserialization bugs.

At your next product review, look at your drop-offs through this four-part lens. If your discovery rate or consent completion rate lags behind technical uptime, stop debugging the API client. Fix the consent messaging, give users control over their bank-linked mobile numbers, and set up state-preserving fallbacks before writing another line of backend code.

That distinction matters in multilingual products. A voice feature is not finished when it recognizes speech; it is finished when a person can safely move from spoken intent to a visible outcome.

Support the way people actually speak#

People may switch languages mid-sentence, use a borrowed technical word, or pronounce a name differently from the spelling stored in a system. Treat those as expected inputs, not edge cases to be cleaned up later.

Sarvam’s Kivi product description, for example, presents a voice app for computer tasks and says it supports 22+ Indian languages and code-switching. That is a useful product signal: language coverage is part of the interface contract, not a model benchmark hidden in the implementation. Sarvam AI, “Everything we announced at Sarvam Epoch,” accessed 2026-09-08.

The experience still needs to show what happened when recognition is uncertain. A transcript that silently changes a name or amount can be more dangerous than an obvious failure. Let the person correct a word, switch the output script when needed, or replay the source before the task continues.

Separate dictation from action#

Typing a message and asking an assistant to send it are different actions. The first creates text; the second changes state outside the conversation. A good interface makes that boundary visible.

Use a three-step pattern for consequential tasks:

1. Capture: show the recognized words and keep the original request available.
2. Review: highlight the fields that carry risk, such as a recipient, amount, date, or account.
3. Confirm: state the action in plain language and wait for an intentional confirmation.

The same rule applies even when recognition is excellent. Accuracy does not replace consent. If a system can both draft and execute, the interface should not make the user guess which mode is active.

Make repair cheap#

A voice interface needs a repair path that is easier than restarting the task. If the system heard the wrong recipient, let the user correct that field without dictating the entire message again. If it heard a sentence in the wrong language, let the user switch without losing the draft.

Test repairs with realistic conditions: a noisy room, a pause, a code-switched phrase, a proper noun, and an interruption. Do not claim support for a language just because the recognizer emits text in that script. Check whether the user can edit, understand and finish the task in that language too.

A useful test case records the spoken input, the expected meaning, the recognized output, the correction available, and the final action. Keep the user’s intent distinct from the model’s transcript so a reviewer can see where the error entered.

Keep the non-voice path first-class#

Voice is not always available or comfortable. A person may be in a shared space, have a speech disability, prefer a keyboard for precise data, or simply want to review silently. These are ordinary conditions, not exceptions.

Offer a visible text alternative and preserve progress when switching modes. Keep buttons and fields usable without speech. If a task is too consequential to complete without review, make that review possible with touch, keyboard, or another accessible input.

Test the whole language journey#

A language checkbox is a weak launch criterion. Test whether the person can start in one language, correct a phrase in another, read the resulting text, and finish the task without losing meaning. A recognizer may handle a spoken sentence while the rest of the product fails on a field label, validation error, or confirmation message.

Build a small test set from real, consented speech or carefully designed examples. Include code-switches, names that resemble common words, numbers spoken in local conventions, and quiet versus noisy audio. For each case, record the intended meaning, the recognized text, the correction offered, and whether the user can recover. Ask a fluent reviewer to assess meaning, not just spelling. Do not claim a language works end to end because one model benchmark looks strong.

Measure task completion, not only recognition#

Word error rate can help diagnose transcription, but it does not tell a product team whether the task succeeded. Track where users abandon, how often they correct recognized text, whether a consequential action gets confirmed, and whether a text alternative is used. Keep denominators explicit: “correction rate among voice sessions” is more informative than a count of edits with no session context.

Review failures by language and task, not only in aggregate. A strong average can hide that one interaction or language pairing is consistently difficult. If a failure cannot be attributed safely, offer a neutral correction path instead of guessing which language the person intended.

Also test the response, not just the input. A product may recognize the spoken request correctly but answer with terminology the person does not use, or show a confirmation that is difficult to read in the chosen script. Let people replay the source audio, edit the transcript, and inspect the final action. Ask reviewers to check whether the response preserves intent and whether the recovery controls are understandable without a training session. A language setting should govern the whole exchange, while still letting a user switch it at any point.

For every voice task, ask: can the user see what was heard, correct it, understand the next action, and complete the job without speaking? If one answer is no, the product has not yet designed the whole interface.

When something breaks, developers tweak the text, eyeball the response in a local playground, and push straight to production. There is no diff review, no regression suite, and no record of why a specific constraint was added.

If your prompts dictate the behavior of your product, you cannot afford to treat them like casual documentation. You need to treat your prompt library with the exact same engineering rigor you apply to application source code.

The unversioned markdown trap#

The moment multiple team members start editing system prompts without version control, subtle regressions creep in. A product manager adjusts tone to sound more professional; a developer removes a formatting rule to save tokens; an engineer inserts a new instruction to fix a parsing bug on Tuesday, inadvertently breaking zero-shot classification on Wednesday.

In a traditional code repository, these changes are caught by pull request reviews and automated tests. In an unmanaged prompt directory, they propagate silently. You only discover them when users complain that the output format changed or the model hallucinated a tool call.

To fix this, prompts must live inside your repository alongside the code that invokes them, tracked by Git. Every modification needs a clear commit message explaining the behavioural hypothesis: “Add explicit JSON schema constraint for extraction step to prevent markdown codeblock wrapping.” If a prompt change causes downstream parsing failures in production, your git log should tell you precisely when and why the instruction was altered.

Versioning templates and variables#

A prompt is rarely static text; it is a parameterized template that combines system instructions, user context, few-shot examples, and state history. When you scatter string formatting across multiple backend services, you invite prompt drift.

Centralize your prompt templates into a dedicated directory structure with explicit schema validation. Each prompt file should declare its required input variables and their expected types.

prompts/
├── extraction/
│   ├── v1_0.jinja
│   ├── v1_1.jinja
│   └── metadata.yaml

When you update a prompt template, bump its version identifier rather than overwriting in place. This allows you to safely canary new prompt versions against a subset of production traffic or test suites before cutting over entirely. Hardcoding version tags in your API calls ensures that an upstream deployment never accidentally relies on an unreviewed template update.

Regression testing against golden inputs#

Unlike traditional unit tests that assert deterministic equality (assert result == 42), prompt evaluation requires probabilistic assertions. A prompt change might improve clarity while altering token count or latency by twenty percent.

You cannot rely on manual playground testing to catch these shifts. Establish a golden test set consisting of 20 to 50 representative input payloads paired with expected output schemas or scoring rubrics. Every time a prompt template changes, run your evaluation harness against both the old and new prompt versions.

If the candidate prompt improves compliance and reduces hallucinations while keeping latency within acceptable bounds, it earns a merge. If schema compliance drops even if the prose sounds better, the pull request is blocked.

Refactoring for conciseness and clarity#

As prompts age, they accumulate defensive instructions—extra sentences added to prevent past failures. Over time, this bloat degrades model attention and inflates costs.

Refactoring a prompt is identical to refactoring legacy code: you look for redundant instructions, conflicting constraints, and overly complex few-shot examples. When an edge case is fixed by adding code validation or schema parsing on the backend, remove the corresponding defensive instruction from the prompt.

Keep your system prompts lean, modular, and focused on behavioral intent. Let deterministic code handle data formatting, retry logic, and validation, leaving the model free to focus on reasoning and extraction.

The path to reliable prompt engineering#

Managing prompts as code transforms prompt engineering from an intuitive art into a disciplined engineering discipline.

Before your next release, take inventory of where your prompts live. Move them into version control, attach a minimal golden test suite, and treat every prompt modification as a pull request. Your error logs will thank you.

In production, delegating database-level orchestration to a probabilistic model produces a brittle agent. It bloats the context window across chatty roundtrips, leaks internal database quirks into the prompt, and creates partial-execution failures where step two mutates state but step three crashes.

If you want an agent to act reliably across complex systems, stop giving it raw database verbs. Give it coarse-grained domain actions that enforce business invariants in code.

The illusion of granular flexibility#

Teams usually choose low-level CRUD tools for two reasons: convenience and the promise of autonomy. An engineer can generate twenty OpenAPI tool schemas in an afternoon by exporting existing route controllers. Product teams often encourage this because fine-grained tools seem to give the agent maximum flexibility to solve unforeseen user problems.

The math behind multi-step tool calls works against that flexibility. Suppose each individual tool selection, parameter extraction, and execution step has an optimistic 95% success rate. If completing a user request requires four sequential CRUD invocations—fetch the record, update status, append an audit entry, and dispatch an alert—the probability of the complete sequence succeeding without error drops to roughly 81% (0.95^4). At six steps, reliability falls to 73%.

Every unnecessary turn between the model and the host environment introduces compounding points of failure:

• The model might misread intermediate JSON output and invent an argument on step three.
• A transient network error on step four can leave the database in an invalid, half-committed state.
• The token cost multiplies because each subsequent turn resends the entire conversation history, including previous tool arguments and verbose payloads.

When you ask an agent to string together five low-level mutations, you are asking a language model to do determinism’s job. Deterministic pipelines belong in application code; probabilistic models belong at the decision boundary.

Why multi-step CRUD loops break in production#

When an agent interacts with granular APIs, three specific failure modes appear repeatedly in production logs.

1. Partial execution and orphaned state#

In standard web applications, a backend developer wraps related mutations inside a database transaction. If the payment record fails to save, the order status does not advance to paid.

When an agent calls granular endpoints across multiple chat turns, there is no shared database transaction across the turns. If the agent calls update_account_status(status="suspended") and then encounters a rate limit or a malformed response when attempting create_compliance_log(), the account remains suspended without an audit trail. The agent cannot reliably roll back previous HTTP calls on its own.

2. Parameter hallucination on wide schemas#

Backend CRUD schemas are notoriously wide. A typical update_user endpoint might accept thirty optional fields, from billing addresses to internal feature flags. When presented with twenty optional parameters, models frequently set defaults that clobber existing data, confuse deprecated fields with active ones, or pass null values for fields they were never meant to touch.

3. Context pollution from raw payloads#

A standard GET /customers/{id} response often returns hundreds of lines of JSON: internal UUIDs, created_at timestamps, hash digests, and nested metadata. Ninety percent of this payload is noise for the task at hand. This raw data consumes context tokens, degrades model attention, and increases latency on every subsequent turn.

The domain action pattern#

The solution is to design tools around domain intents rather than database tables. A domain action is a coarse-grained function that encapsulates a complete business workflow behind a single, tightly constrained interface.

Instead of exposing four separate tools: - fetch_invoice_details(id) - update_invoice_status(id, status) - record_discrepancy_note(id, note) - notify_finance_reviewer(id, email)

You expose one domain tool: - resolve_invoice_discrepancy(invoice_id, resolution_type, explanation, notify_reviewer)

The backend implementation behind resolve_invoice_discrepancy executes inside a single application boundary. It validates whether the invoice is in an editable state, performs the database mutation, writes the audit log, triggers the notification, and wraps everything in a database transaction that rolls back if any step fails.

{
  "name": "resolve_invoice_discrepancy",
  "description": "Resolves an invoice hold by applying an approved resolution rule, updating the audit trail, and notifying the assigned reviewer.",
  "parameters": {
    "type": "object",
    "properties": {
      "invoice_id": {
        "type": "string",
        "description": "Unique identifier of the invoice on hold."
      },
      "resolution_type": {
        "type": "string",
        "enum": ["waive_fee", "rebill_line_item", "escalate_to_controller"],
        "description": "The approved business resolution path."
      },
      "explanation": {
        "type": "string",
        "description": "The justification grounded in the customer contract or dispute history."
      }
    },
    "required": ["invoice_id", "resolution_type", "explanation"]
  }
}

Notice what disappears: internal status flags, foreign key IDs, user IDs, and timestamps. The tool schema only asks the model for decisions that genuinely require reasoning. Everything else is derived from the authenticated session and business logic.

How to evaluate tool schema boundaries#

When auditing your agent’s tool definitions, apply three criteria to decide whether a tool is at the right level of abstraction:

The atomicity test#

If step B must always happen when step A happens, step A and step B should never be two distinct tools in the agent’s catalog. If updating a customer tier must always write a regulatory audit record, build a single tool that takes the tier change and reason, then writes both records in one transaction.

The argument minimization test#

Inspect every parameter in your tool schema. If a parameter can be computed deterministically from the database, the current timestamp, or the user’s authentication context, remove it from the schema. An agent should never be asked to pass updated_at, modified_by_user_id, or organization_id.

The evidence-dense response test#

When a tool finishes execution, it should return an evidence summary, not an object dump. A response like: {"status": "applied", "invoice_id": "INV-4021", "amount_waived": 45.00, "new_balance": 310.00} gives the model exact evidence to formulate its response without flooding the context window with raw schema baggage.

A checklist for your agent’s tool catalog#

Before shipping an agent feature that mutates system state, review your tool registry against these five questions:

1. Are transactions handled by the code or the prompt? If an agent fails midway through a task, does the system stay in a consistent state without requiring cleanup?
2. Are inputs constrained to enums and verified types? If a field accepts only three business states, are they defined as an enum in the schema rather than documented in the system prompt?
3. Does any tool expose raw database IDs or internal flags that the model must coordinate? If the model needs to pass an ID from Tool A into Tool B just to mutate state, combine the two tools into a single workflow.
4. Is destructive action decoupled from ambiguous discovery? Can the model query state and dry-run potential changes without triggering live side effects?
5. Does the tool response provide only the evidence needed for the user-facing answer? Strip out unindexed metadata, nested relationships, and verbose system traces before the result enters the context.

If your agent is struggling with consistency, the problem is rarely that the underlying model lacks intelligence. More often, the agent is being asked to do the work of a backend framework. Move deterministic state transitions into your application code, keep business invariants safe, and let the agent focus on high-judgment decisions.

Make the queue answer four questions#

For each exception, show four things together: who owns it, what decision is needed, by when, and what happens next. If any field is missing, the item is not ready to be treated as routine queue work.

For example, “document mismatch” is a reason, not an action. A more useful item might say: “Operations reviewer — compare the submitted name with the source record — due tomorrow — request clarification if they differ.” The exact owner and deadline depend on the workflow, but the shape is reusable.

Avoid assigning every exception to a generic team inbox. A team can be accountable while no individual notices a new item. If individual assignment is not possible, make the team’s triage rule explicit: who checks the queue, how often, and who takes over when the usual owner is absent.

Separate waiting from working#

An exception may be waiting on an internal decision, a customer response, or another system. Those are different states because they imply different next actions. “Waiting on customer” should identify who will follow up and when; otherwise it becomes a polite label for forgotten work.

A small state model is usually enough:

• Unassigned: needs triage.
• In progress: an owner is investigating.
• Waiting: blocked on a named dependency, with a review date.
• Resolved: decision recorded and downstream action completed.

Do not add states merely to represent every possible cause. Store the cause separately from the work state; “missing field” can be the reason whether the case is unassigned or already being investigated.

Design the escalation before the dashboard#

Set a rule for overdue work before adding a red badge. For instance: at the review date, notify the owner; after the next missed review, route the case to the owner’s lead. A notification without a reassignment or explicit decision path only makes the backlog louder.

When designing a queue, test one ordinary case, one ambiguous case, and one case whose owner is unavailable. For each, ask: can someone tell what decision is pending, who must act, and when the workflow will surface a stall?

If the answer is no, fix ownership and next actions before adding more status labels.

An agent’s reasoning ability is fragile. When you force it to switch between radically different tasks or data domains within the same execution loop, you are not just asking it to do more work—you are increasing the probability that it will lose the thread of its original instruction.

The cost of state jumps#

When an agent is mid-reasoning, it maintains a implicit state of its current task. When you inject a request to switch context—perhaps to perform a quick search, or to summarize a document that is tangentially related—the agent has to re-orient itself.

For simple tasks, this is often fine. But for complex workflows, every state jump introduces a chance for the model to hallucinate or misinterpret previous constraints.

Designing for continuity#

To build reliable agentic systems, we have to treat agent context as a finite resource:

1. Keep the scope narrow: If an agent is designed to manage a specific part of a workflow, do not give it the authority to branch into unrelated tasks unless absolutely necessary.
2. Handoffs over switches: If a task requires a significant shift in data or perspective, it is almost always better to hand that task off to a specialized sub-agent. This keeps the primary agent’s context clean and focused on its core responsibility.
3. Minimize interruptions: Instrument your workflows so that the agent completes a logical segment of its task before it receives new information.

When we prioritize the continuity of an agent’s reasoning process, we reduce the likelihood of compounding errors, leading to systems that are more predictable and far easier to debug.

The real challenge isn’t just getting the agent to “answer”; it’s ensuring that when the agent is uncertain, the interface provides enough context for the user to understand why and how it reached that decision.

The trap of seamless automation#

We often design interfaces to be seamless. We want the user to click “Run” and get a result. For deterministic tasks, this works. For agentic workflows involving interpretation, inference, or synthesis, a seamless interface hides the agent’s logic.

When the agent makes a choice based on incomplete information or ambiguous signals, the user needs to know what those signals were. If the interface hides this, the user is left to guess whether the agent was confident, or if it was just forced to choose the “least bad” option.

Exposing the trade-offs#

Instead of presenting the result as absolute fact, design the interface to expose the trade-offs.

If an agent is summarizing a set of conflicting inputs, don’t just show the summary. Show the weight it gave each input. If an agent is deciding on a next step in a workflow, don’t just execute the step. Show the alternatives it considered and why it discarded them.

This changes the user’s role from a passive observer to an active curator. It reduces cognitive load because the user doesn’t have to reconstruct the agent’s reasoning from scratch; they are presented with the parameters of the decision, allowing them to rapidly validate or correct the agent’s logic.

Designing for transparency#

This requires a fundamental shift in how we think about agent UI:

1. Confidence metrics: If the model provides a confidence score, surface it. If it doesn’t, create a heuristic based on the consistency of the underlying data.
2. Reasoning trails: Include a view that breaks down the steps taken, especially for multi-step agents.
3. Alternative paths: When a decision involves selecting one path over another, briefly show what would have happened if the other path were chosen.

When we treat ambiguity as a feature of the interaction—rather than a flaw in the output—we build systems that are significantly more reliable and much easier to trust.

Framing AI features as experiments rather than fixed requirements changes the nature of the development. It acknowledges that the system might not work as intended at launch, and it shifts the team’s focus from “did we build it?” to “did we learn enough to iterate?”

Define the hypothesis, not just the spec#

A standard requirement says “the AI will summarize documents.” An experiment hypothesis says “by adding a summary, we expect users to spend 20% less time reviewing each document, without increasing the rate of missed information.”

The difference is the metric. If the AI summarizes but users ignore it because they don’t trust it, you have met the requirement but failed the experiment. If you don’t know what you are trying to learn, you won’t know if you have succeeded until long after launch.

Use a “kill or pivot” criteria#

An experiment needs a stopping rule. If the AI doesn’t meet the performance baseline, or if users find the summary unhelpful, what happens next?

If you treat the feature as a fixed requirement, you will likely try to “fix” the prompt or the model, potentially wasting weeks on a feature that users fundamentally don’t need. If it’s an experiment, you have pre-defined conditions for stopping. If the data shows it doesn’t solve the problem, you kill it or pivot the approach before the team gets invested in the implementation.

Build the feedback loop into the release#

Product managers often ask “how do I know if the AI is good?” The answer is rarely in the logs. It’s in how users interact with the feature.

Design the release so you can instrument those interactions. Are they copying the summary? Are they regenerating it? Are they editing it before using it? Those signals are the raw data for your hypothesis.

If you cannot instrument the outcome, you are not running an experiment; you are guessing. And in AI, guessing is the most expensive way to build a product.

I treat a decision log as a small companion to the spec. It is not meeting minutes and it is not a place to defend every choice forever. Its job is to make important choices legible enough that the team can execute them now and reconsider them intelligently later.

Capture choices, not conversation#

A meeting transcript records what was said. A decision log records what the team will do, and the boundary around that commitment. The distinction matters because discussion often contains tentative ideas that never become decisions.

For example, imagine a team deciding how a document-review tool should handle an unreadable upload. The transcript might include several possible responses: ask for a clearer file, try a second extraction method, or let a person review it. The log should say which behavior ships first, why, and what happens when it fails. It should not preserve every suggestion as though it were still under consideration.

A useful entry can fit in a few lines:

The table is a prompt, not paperwork to complete for every tiny detail. Use it for choices that affect user outcomes, architecture, scope, risk, or dependencies. If a decision can be reversed in minutes and has no meaningful knock-on effects, recording it may cost more than it saves.

Keep evidence separate from assumptions#

A rationale becomes brittle when opinion is presented as fact. Write down what is known, what is inferred, and what remains uncertain. That lets someone update the decision without having to reject the entire argument.

Suppose a team chooses not to support a certain file format in the first release. The evidence might be that the current parser cannot reliably extract its contents. The assumption might be that few target users need it. The decision could be to show a clear unsupported-format message rather than silently accepting the file. Those are three different statements, and they age at different speeds.

A practical template is:

Evidence: what we observed or can verify. Assumption: what we believe but have not established. Choice: what we will do given both. Revisit when: what signal would change the balance.

Avoid vague rationales such as “best UX,” “industry standard,” or “engineering prefers it.” Replace them with the actual trade-off: “We will ask for a replacement file rather than return a partial summary, because a partial result could be mistaken for complete coverage.” That sentence makes the user risk visible and gives a future reviewer something specific to test.

Do not manufacture certainty to make a decision sound strong. If the evidence is thin, state that the choice is a time-boxed hypothesis. A team can still move forward; it just knows what it is betting on.

Define the reversal condition before launch#

“Revisit later” is not a trigger. It is a promise that usually gets crowded out. A useful trigger is concrete enough that someone can notice it without guessing what the original author meant.

For a decision about manual review, a trigger might be: “Reopen this if the supported input types change, or if we observe repeated cases where the current fallback blocks completion.” This avoids inventing a numeric threshold when no baseline exists, while still naming the events that matter.

When a quantitative threshold is appropriate, record its denominator and source. “Review if more than five of the last fifty uploads need manual intervention” is more interpretable than “review if failure rate is high.” But only use a number the team can actually measure. A precise-looking threshold with no instrumentation is decoration.

A reversal condition should also name what is not enough. A single anecdote may prompt investigation without automatically overturning the decision. Conversely, a safety or compliance concern may require immediate review even before a recurring pattern appears. Distinguish the trigger for learning from the trigger for changing course.

Connect decisions to the work#

A log hidden in an old document will not help a team at the moment it makes a change. Link the relevant entry from the requirement, ticket, design, or launch checklist where the choice affects execution. Keep one canonical entry and reference it; copying the rationale into several places creates multiple versions that drift.

A product manager is often well placed to maintain this record, but the reasoning belongs to the people who made the choice. Ask the engineer about system constraints, the designer about interaction consequences, and the relevant domain owner about policy or operational limits. Attribute the decision to the accountable group or owner, not to a fictional consensus.

A review should be quick: scan entries whose triggers have fired, close those that no longer matter, and assign an owner to investigate the uncertain ones. If every item remains permanently “open,” the log has become a museum rather than a working tool.

Use the log to make change cheaper#

The goal is not to prevent decisions from changing. It is to make change less expensive and less personal. When someone challenges a choice, the conversation can start with the context and evidence instead of reconstructing who said what in a meeting months ago.

Before calling a PRD ready, ask:

• Which choices would surprise the team if they changed next week?
• For each one, can a new teammate find the rationale and the rejected alternative?
• Are facts and assumptions clearly distinguished?
• Is there an owner and a recognizable revisit trigger?
• Does the linked work point to one current source of truth?

If the answer is no, add only the missing decisions. A concise record of five consequential choices is more useful than a transcript of fifty conversations.

Make the transfer inspectable#

Treat the handoff as a small interface contract, not a completion message. Include four fields:

• Outcome: what changed or what decision is being proposed.
• Evidence: the specific inputs, tool results, or records supporting it.
• Uncertainty: what could not be confirmed, including missing or conflicting information.
• Next action: who should do what, and whether it is safe to proceed before review.

For example, “Vendor record updated” says little. A stronger handoff says: “Updated the billing address using the address in the signed order form; the account profile had a different postcode. I did not change the tax registration field. Please confirm the postcode conflict before the next invoice is issued.” The recipient can verify the source and see the unresolved boundary immediately.

Separate evidence from confidence#

A confidence label is not evidence. “High confidence” does not tell a reviewer which source was used or whether the agent actually checked the relevant field. Keep the evidence concrete: name the source type, quote the relevant value where appropriate, and state what was compared. Avoid copying sensitive content into a handoff when a secure reference or record identifier will do.

This also helps when the work moves between agents. The next agent should receive the observations and constraints, not just a summary that has already compressed away caveats. If the evidence cannot be passed safely, pass a reference and an access instruction instead.

Define when the handoff blocks action#

Not every uncertainty needs a human pause. Make the boundary explicit with a simple rule: proceed only when the evidence source is authoritative, required fields agree, and the action is reversible. Otherwise, route to review and name the unresolved question.

That rule is more useful than a generic “human in the loop” label because it tells the system what event triggers the loop. It also gives the reviewer a bounded task instead of asking them to re-do the whole workflow.

Before shipping an agent handoff, check: Can the recipient identify the proposed outcome, inspect its basis, see what is uncertain, and know whether action is blocked? If any answer is no, the handoff is not finished.

A generic “Something went wrong” tells a person nothing about whether they should retry, rephrase, provide more context, or switch to another path. The fallback is part of the product interface, not an implementation detail.

Give uncertainty a useful shape#

Start by distinguishing three cases: the system lacks information, the request is ambiguous, or the model’s output failed a quality check. They need different next steps.

• If a source is missing, say which source or detail would help.
• If the request has two plausible meanings, show the choices and let the user select one.
• If the answer fails a quality threshold, say that the feature could not produce a dependable result and offer the existing non-AI route.

Do not ask the user to “try again” when another attempt is unlikely to change the evidence. Do not present an uncertain answer as complete just to avoid an empty state.

Keep the user’s task moving#

A good fallback preserves what the user already entered, explains what happens next, and avoids making them start over. If the system can safely complete part of the task, label that partial result. If it cannot, make the manual path easy to find.

Before launch, test at least these states: no relevant source, conflicting sources, unclear intent, a timed-out request, and a low-confidence result. For each one, specify the message, the available action, and whether the user’s input is retained. Treat a repeated timeout differently from a single slow response: after a retry budget is reached, move the person to another path rather than asking them to keep clicking.

The practical rule: whenever the AI path stops, the product should still tell the user what they can do next.

I get more value when the first request is not “implement this.” It is “tell me what you would need to know before implementing it.”

Separate the question from the solution#

A feature request usually bundles an outcome, a possible design and a set of hidden assumptions. For example: “Add a comparison view so a manager can spot unusual changes.” The outcome might be faster review. The proposed design is a comparison view. The assumptions may include that the manager has a stable baseline, can identify what counts as unusual, and has permission to see both records.

Ask the coding assistant to inspect the relevant code and return four things before it edits anything:

1. The current behavior, with file and function references.
2. The smallest product assumption that could make the proposed feature unnecessary or unsafe.
3. Two implementation shapes and what each would require.
4. A cheap test that would change the decision to build.

This does not make the assistant a product strategist. It gives the PM a structured way to use the tool’s code-reading ability without letting its first implementation become the default answer.

Bound the context, not just the prompt#

A long prompt can still produce a weak answer if the tool is pointed at an entire repository with no boundary. The model may spend its context on unrelated files, infer behavior from stale documentation, or edit a shared component when the task is local.

Name the files or folders it may inspect, the files it may change, and the paths it must not touch. If the relevant area is unknown, ask for a read-only map first. Then review the map and widen the boundary deliberately. The instruction “do not modify files” is more reliable than assuming an assistant will know that exploration should remain read-only.

A useful task brief fits in a small template:

The examples are hypothetical. The point is to make the boundary observable: if the diff changes a forbidden area, it is easy to reject before debating code quality.

Ask for alternatives with costs#

When the assistant finds more than one plausible approach, ask it to compare them against the same constraints. “List alternatives” is too loose; it invites a list of implementation patterns with no decision relevance.

Ask for the smallest reversible option, the option that best preserves future flexibility, and the risk each introduces. For the comparison example, a temporary side-by-side view might answer the review question without changing the underlying record model. A persisted history feature could support more workflows but would introduce retention, access and migration decisions.

Do not ask for arbitrary scores unless the inputs mean something. A table with “what this makes easier,” “what it makes harder,” and “what we still need to learn” is often more useful than a synthetic ranking.

Make the prototype answer one question#

A prototype is valuable when its result can change a decision. Before letting the assistant build it, finish this sentence: “If the prototype shows , we will ; if it shows , we will .” If neither branch changes what the team does, the prototype is probably a demo rather than a test.

Keep the prototype narrow enough to inspect. A small script that compares two representative records may be more informative than a fully integrated screen. Use synthetic or approved sample data. If the task depends on real user information, do not paste it into a tool unless the data handling is explicitly permitted.

The assistant can produce the test harness, but the PM still chooses the input cases and the success condition. Ask it to explain which cases are missing and why. Then add the cases that represent a realistic failure: no baseline, a deleted field, a permission boundary, or conflicting values.

Treat the diff as a claim#

Generated code is a claim that a particular change solves the stated problem. Review the claim against the task, not against how plausible the code looks.

A compact review has four passes:

• Scope: Did it touch only allowed files?
• Behavior: Does the change match the user outcome rather than merely the requested UI?
• Evidence: Did the focused test run, and does it fail without the change?
• Risk: Does the change alter data access, persistence, or a shared contract?

If a test cannot run, the output is not verified. If a result depends on a manual judgment, record who made it and what they saw. “The assistant said the tests pass” is not a substitute for seeing the test result.

A better first prompt#

Try this before asking a coding assistant to implement a new product idea:

Read only the listed files and do not edit. Summarize the current behavior with code references. List the assumptions that must be true for this feature to help the user. Give two bounded implementation options, their risks, and one reversible test that could change whether we build it. Stop after the analysis.

After reviewing that output, decide whether the problem is understood. Then give the assistant a small implementation task with allowed files and a test condition. The tool may still write the code; it just no longer gets to decide what the code is evidence for.

Before the next AI-assisted build, write down the product question, the allowed context, and the result that would change your mind. If any of those is missing, ask for the map before the patch.

When you test software, you map inputs to outputs. You cover branches: the if-statement fires, the loop runs, the edge case at zero doesn’t crash. You achieve coverage. The model, though, doesn’t execute branches. It computes probability distributions over tokens. A test that passes isn’t evidence the model is robust; it’s evidence the test was written in a way the model learned to handle.

The deterministic illusion#

You write a test like:

Input: "What is 2 + 2?"
Expected: "4"
Result: PASS ✓

You write fifty more like it. The model passes all fifty. You think you’re done.

What you’ve actually done: you’ve found fifty points in semantic space where the model learned to output the right token. You haven’t tested robustness. You’ve tested fifty inputs that look like the ones you thought of.

The problem: your eval set covers a small patch of a very large input space. The moment a user writes something you didn’t anticipate, a different phrasing, a harder number, a logical twist, you have no evidence either way about what the model will do.

Where edge cases hide#

In software, edge cases cluster at boundaries: zero, negative numbers, empty lists, null pointers. You find them by reasoning about the code. In LLMs, edge cases are distributed across semantic space. They’re not at boundaries; they’re everywhere you didn’t write a test.

Consider a feature that summarizes legal documents. Your eval set has:

• 40 summaries of mortgage agreements ✓
• 30 summaries of employment contracts ✓
• 20 summaries of NDAs ✓
• 10 edge cases: very short documents, documents with unusual formatting

You test all ninety. The model passes. You ship.

A user gives it a contract written in fragments, with embedded definitions that reference other clauses. The model hasn’t seen this structure in your eval set. It fails.

The test you missed wasn’t at a boundary. It was in a region of input space your examples didn’t cover. You can’t reason your way to it. You can’t enumerate all possibilities. You have to find it.

Two practical moves#

Adversarial sampling. Have a person—or another LLM—write inputs specifically designed to break your model. Not random inputs. Targeted attacks: ambiguous phrasings, contextual traps, logical puzzles where the model usually fails. Evaluate your model on these adversarial examples. Every failure is a new eval row; every pass is evidence for that region, not the whole space.

Statistical coverage instead of case coverage. Instead of “I’ve tested fifty inputs,” think: “I’ve sampled from a distribution of inputs. How much variance does my eval set cover?” Take your 50 test cases and measure the semantic diversity: use embeddings, cluster them, plot them. Are you sampling from across the space, or just hitting the same region repeatedly? If you see three tight clusters in embedding space, you’re testing three easy cases over and over.

The pattern to watch for#

If your eval set is written by the team building the feature, it will lean toward cases the team thought of and cases the prompt was already tuned against. Ask someone outside the team, a user, a support lead, another PM, to write test cases without seeing your prompt. Compare their eval set to yours. The tests they write that your model fails are the gaps you can’t see from the inside.

The real rule#

A passing eval set is not evidence of robustness. It’s a report of what your tests could measure. Robustness is what happens when the model sees inputs outside your test’s semantic cluster.

Build an eval set that moves. Rotate in fresh adversarial examples. Sample from outside your comfort zone. The edge cases you find by searching are edge cases you can fix.

The product problem is not merely to make the application form shorter. It is to make responsibility and the next move visible across the people and systems that carry the case.

Model work, not just records#

A loan application is a record, but the workflow is a series of actions: information is supplied, checked, resolved, reviewed, and eventually closed or continued. The states should describe what is happening to the work, not just how much information is present in the form.

For every state, write down:

If any cell is blank, the status is likely to become a parking lot. “Waiting for review” is not an operational state if the system cannot identify the queue, owner, or next event.

Separate missing information from review#

A request for a document and an internal verification are not the same kind of wait. The first needs a clear ask to the applicant; the second needs a work queue and an owner. Combining them creates unhelpful notifications and makes it difficult to know whether the customer or the institution has the next move.

Use distinct states such as “information requested,” “information received,” and “under review,” but only if the people operating the workflow can act on those distinctions. Each state should have a transition rule and an exit condition. If the product cannot tell whether a document is sufficient, it should not automatically label the case “complete.”

Show the reason for the wait in language the relevant person can use. “More information required” is weaker than “Please provide the page that shows the requested repayment date.” The exact wording depends on the process; the rule is that the request must name the missing evidence and what will happen after it arrives.

Design the exception path before the happy path is polished#

A workflow designed only for a complete, legible application will push exceptions into email, spreadsheets, and memory. That is where ownership becomes ambiguous and the product loses its record of why a decision was delayed.

List the exceptions that alter the next action: unreadable information, conflicting values, duplicate submissions, a deadline that has passed, or a case that needs a human review. For each, specify who receives it, what they can decide, and what evidence they must leave behind.

Do not turn every exception into a free-text comment. Free text can capture nuance, but it does not reliably route the work. Pair it with a small set of structured reasons and a clear escalation owner. If the situation does not fit the list, capture the explanation without pretending the case is in a known state.

Measure the handoffs#

A single end-to-end duration can hide where the workflow is stuck. Measure the time between meaningful handoffs: request to submission, submission to review, review to decision, and decision to communication. State the start and end event for each interval so that a dashboard does not compare incompatible clocks.

Then segment by case type or route only when those distinctions are supported by the data and useful to an operating decision. A long wait caused by missing information may need better instructions. A long internal review may need queue ownership or policy clarification. Averages can obscure a small group waiting far longer; inspect the distribution and the oldest open cases as well.

Do not optimize elapsed time by hiding necessary checks. In a financial workflow, speed is valuable only if the product preserves the evidence and review required for a sound decision. Make the speed measure sit beside the quality and exception measures, not in place of them.

Make the next step legible to every participant#

Applicants need to know whether to act, what to provide, and whether their submission was received. Operators need a queue they can work and a record of what is outstanding. Decision-makers need the evidence and the unresolved questions, not a green badge that implies certainty.

That does not mean every participant sees every field. Permissions and data minimization still matter. Design the workflow so each role sees enough to perform its action and no more than the role requires.

A handoff also needs a time expectation. “Assigned” does not tell an operator or applicant when the next update should arrive. Define the expected review window, what message appears if that window is missed, and who can unblock the queue. Do not promise a decision time the team cannot control; distinguish an internal target from an external dependency. This makes delays visible without implying that every case should follow the same path.

A useful prototype can be a state-transition table before it is a new screen. Put one ordinary case and two exceptions through it. For each transition, check that the owner, trigger, permission, notification and audit record are explicit. If the next move cannot be answered from the product, fix the workflow model before polishing the dashboard.

A stopping rule sounds like an implementation detail. It is a product decision: it defines how much work the system may do, what it is allowed to infer, and when a person takes over.

A goal is not a completion contract#

“Find the renewal date and prepare a reminder” looks specific until an agent has to execute it. Which folder should it search? What if two documents contain different dates? Is drafting the reminder enough, or should it send one? If it cannot find the date, should it search every connected drive or ask the user?

A goal describes a destination. A completion contract describes the evidence that the destination was reached and the boundary beyond which the agent must not continue.

For that example, a first contract could say:

• Search only the user’s selected contract folder.
• Return the date with a link to the source passage.
• Draft a reminder, but do not send it.
• If the sources disagree or no date is found, stop and show what was checked.

That is less magical than “handle renewals for me.” It is also testable. The user can tell what happened, and the team can tell whether the agent followed the intended path.

Define “done” in observable terms#

An agent should not decide it is done because its last message sounds complete. Done should correspond to a state a person or system can verify.

For a read-only research task, the finish line might require a result and a source. For a record update, it might require a successful response from the system and a read-back showing the new value. For a draft, it might mean the draft exists in the expected place and remains unsent.

Write the completion condition as a small checklist:

The distinction between “attempted” and “completed” matters. A tool returning without an error may only mean the request was accepted. If the outcome matters, read it back. If it cannot be verified, say so instead of converting an attempt into a success claim.

Put a budget on actions#

Token limits and timeouts protect infrastructure. They do not tell the product how much autonomy is appropriate. A user-facing agent also needs an action budget: a limit on searches, retries, mutations, or elapsed time for one request.

For a first version of the read-only renewal lookup, I might start with five document searches, one follow-up search if a source is incomplete, and a two-minute deadline. Those are hypotheses to test against real tasks, not universal numbers. The important part is that the agent has a defined point at which it must stop and report what it found.

Separate the budget by action type. Reading one more document is not equivalent to sending a message or changing a record. A useful policy might allow several read-only lookups, permit one retry after a transient error, and require explicit approval before any irreversible action. Never let a retry silently broaden permissions or turn a draft into a sent message.

Then measure where the budget is spent. If successful tasks regularly need one more search, adjust the search cap. If retries repeat the same failure, change the recovery path rather than raising the cap. More autonomy should follow evidence that the extra action improves the result without creating a worse failure mode.

Make stopping conditions explicit#

“Stop when confused” is too vague to implement or evaluate. Name the conditions that end the run:

• Missing information: a required field is absent from the permitted sources.
• Conflicting evidence: two sources disagree and no precedence rule resolves them.
• Permission boundary: the next step needs access or approval the agent does not have.
• Repeated failure: the same tool action fails again after its allowed retry.
• Budget exhausted: the remaining task cannot be completed within the action or time limit.

Each condition needs a user-facing result. Missing information should name the missing field. Conflicting evidence should show both sources. A permission boundary should ask for the specific approval needed. Budget exhaustion should summarize completed and unfinished steps.

This turns stopping into a designed path instead of an error state. It also gives the team a useful set of evaluation cases: one for each reason the agent should stop, plus one where it should continue.

Make partial progress legible#

A task is not always all-or-nothing. If an agent finds the date and prepares the reminder but cannot save the draft, it should not report “done” or return a generic failure. It should say which parts are complete, which are not, and why it stopped.

I would make the final status one of three things:

1. Complete: all required outcomes were verified.
2. Partial: some outcomes were verified; unfinished steps are named.
3. Blocked: no safe next action is available without new information or approval.

Keep that status separate from the natural-language summary. The interface can show a concise sentence, but the underlying result should preserve the status, completed actions, evidence, and stop reason. That makes the experience clearer for users and the behavior easier to audit later.

The stopping-rule review#

Before shipping an agent, take one normal request and walk it through these questions:

1. What exact evidence proves the task is complete?
2. How many searches, retries, and state-changing actions are allowed?
3. Which conditions require stopping or asking the user?
4. Can the agent distinguish a successful attempt from a verified outcome?
5. If it stops halfway through, can the user see what remains?

If those answers are missing, the agent does not yet have a product contract. Add the stopping rule before adding another tool.