DEV Community: anassBld

How to handle scope creep without ruining the client relationship

anassBld — Sun, 23 Aug 2026 04:34:06 +0000

If you build websites for clients, you know the feeling. The project is 95% done, and you get the email: "Could we just add a quick careers page? Oh, and maybe a small integration with our CRM? Should be quick!"

It's never quick. But saying "No" feels confrontational, and saying "Yes" eats into your margin until you're working for below minimum wage.

The "One More Thing" Trap

The problem isn't the client asking. The problem is that freelance web designers usually respond with a paragraph of text explaining why it's hard.

Clients don't read paragraphs. They read prices and timelines.

How to standardize scope changes

Next time a client asks for something out of scope, don't write an essay. Put the request through a structured filter and offer them one of five explicit choices:

Included: It's genuinely tiny. Do it, but document that you did it for free so it holds value.
Price: "Yes, we can add that CRM integration. It will add $850 to the budget and push launch back by 4 days. Let me know if you want to proceed."
Swap: "We can add the careers page, but to keep the launch date and budget the same, we'll need to drop the custom team-member illustrations."
Park: "Great idea. Let's put this in the 'Phase 2' backlog and tackle it right after we launch Phase 1."
Decline: "This requires a custom backend we don't specialize in. I recommend bringing in a dedicated backend dev for this."

Standardize your response

When you remove the emotion and present choices, clients respect the boundary. They usually choose "Park" or happily pay the "Price".

If you struggle with wording these emails or estimating the impact of a request, I've put together a structured workbook and offline calculator to handle exactly this.

You can grab the Scope Change Control Kit for Web Designers on my Gumroad here: https://gridquill.gumroad.com/l/scope-change-control-kit-web-designers

It includes the offline calculator, copy-ready client messages for all five scenarios, and a reusable request log. Stop working for free, and start getting paid for your expertise.

Your AI Agent shouldn't own its own memory. Here's why.

anassBld — Sat, 22 Aug 2026 10:45:12 +0000

When building AI agents, the standard tutorial approach is to pass a sliding window of chat history directly back to the LLM on every turn. The LLM acts as both the reasoning engine and the state manager.

For simple chat bots, this is fine. For production agents taking actions (API calls, database writes), this architecture is a ticking time bomb.

The Problem: Probabilistic State

LLMs are probabilistic. If an agent executes a tool call (e.g., charge_credit_card), and the API times out, the LLM has to guess what happened based on the error string. Did the charge go through and the connection drop? Or did it fail immediately?

If the LLM owns the state, it might hallucinate a successful charge, or worse, hallucinate a failure and retry the action, double-charging the customer.

The Solution: Deterministic Outer Loops

The reasoning engine (the LLM) should be completely decoupled from the state machine.

The LLM outputs intent: "I want to call charge_credit_card."
The Outer Loop executes it: A deterministic, traditional state machine (written in Python/TS) intercepts the intent, logs it to a database as pending, and executes the call.
Out-of-band Verification: If the call times out, the outer loop does not blindly ask the LLM what to do. The outer loop pauses the agent, runs an out-of-band verification (e.g., checking the Stripe ledger), updates the exact deterministic outcome (success or failed), and only then hands the state back to the LLM.

Stop letting your LLMs manage their own state. Treat them as pure transformation functions: Context -> Intent. Your deterministic harness must handle the rest.

Timeout Is Not Failure: The State Your AI Agent Is Missing

anassBld — Tue, 18 Aug 2026 19:56:57 +0000

When an AI agent's HTTP request or browser tool call times out, what does your system record?

If it records failed, the agent has a blind spot. A network timeout does not mean the operation failed on the remote server; it means the connection closed before the client received the answer. If the server processed the mutation, retrying the call blindly will create a duplicate artifact: a double payment, a duplicate ticket, a repeat email, or a redundant article.

If it records succeeded, it is hallucinating certainty.

The missing state is outcome_unknown—a first-class operational status that halts automatic retries, records the unconfirmed mutation, and hands off execution to an explicit reconciliation loop.

In our previous post, we discussed why agents need action receipts rather than purely semantic memory. Following valuable discussions with practitioners on distributed systems and memory boundaries, this article turns that concept into a concrete, testable state machine you can drop into any production agent framework.

The Line: Pre-Send Failure vs. Post-Send Ambiguity

Not all exceptions are created equal:

[Intent Recorded]
       |
       v
[Attempting Transport] ---> (DNS / Local Socket / Auth error) ---> [REJECTED / SAFE_TO_RETRY]
       |
  (Bytes sent)
       |
       v
[Awaiting Response]   ---> (Connection Timeout / Drop / 504)  ---> [OUTCOME_UNKNOWN]

Pre-Send Failures: If the DNS lookup fails, credentials are missing locally, or the connection is refused before a single byte leaves the socket, the world hasn't changed. The action is deterministically unexecuted and safe to retry.
Post-Send Ambiguity: The moment bytes cross the wire, transport failure ceases to be an indicator of server state. The server may have committed the mutation and crashed during response serialization, or an intermediate proxy timed out after 30 seconds while the backend worker finished the job.

Treating post-send ambiguity as a failure is the root cause of automated duplicate storms.

The State Machine

Here is the complete lifecycle of a guarded agent action:

State	Type	Description	Allowed Next Transitions
`planned`	Transient	Intent recorded locally with safe payload fingerprint.	`submitted`, `rejected`
`submitted`	Transient	Bytes sent to remote endpoint; awaiting response.	`succeeded`, `rejected`, `outcome_unknown`
`outcome_unknown`	Suspended	Network dropped or timed out after submission. Retries blocked.	`reconciling`, `manual_review`
`reconciling`	Active	Querying external system for proof of effect.	`succeeded`, `safe_to_retry`, `manual_review`
`succeeded`	Terminal	External ID verified via response or readback.	None
`safe_to_retry`	Terminal	Absence of effect proven via authoritative readback.	None (new intent required)
`rejected`	Terminal	Server returned deterministic client error (4xx).	None
`manual_review`	Terminal	Absence/presence cannot be proven programmatically.	Human intervention

Idempotency Keys vs. Intent Fingerprints

In payment engineering, distributed consensus is achieved through at-least-once delivery paired with a server-side deduplication key (an Idempotency Key).

When an external platform natively supports idempotency headers (such as Idempotency-Key: <uuid> in Stripe or GitHub GraphQL mutation keys), reconciliation is straightforward: if you time out, you re-send with the exact same key.

However, the vast majority of web APIs, CRUD services, and browser-driven surfaces do not support native idempotency keys. In those environments, the caller must carry the burden:

Normalized Intent Fingerprint: Before sending, compute a canonical cryptographic hash of the semantic payload (mutation type, resource target, normalized body fields).
Read-After-Write Reconciliation: When outcome_unknown triggers, the agent queries the read API (or search endpoint) for resources created by the agent's account within a bounded timestamp window matching the intent fingerprint.

import hashlib
import json

def compute_intent_fingerprint(method: str, path: str, payload: dict) -> str:
    canonical = json.dumps(
        {"method": method.upper(), "path": path, "payload": payload},
        sort_keys=True,
        separators=(",", ":")
    )
    return f"sha256:{hashlib.sha256(canonical.encode('utf-8')).hexdigest()}"

Retaining the Ambiguity Audit Trail

A subtle trap in state machine design is destructive in-place updates.

If an action goes submitted -> outcome_unknown -> reconciling -> succeeded, and you simply overwrite the state to succeeded, you destroy the historical record that the action lived in an indeterminate state for hours.

During post-mortems (or when auditing race conditions where another worker observed missing state during that window), knowing how an action reached success is as critical as the final state.

A robust action receipt preserves the full transition trajectory:

{
  "operation_id": "20260818T190000Z-a1b2c3d4e5",
  "operation": "articles.create",
  "state": "succeeded",
  "intent_fingerprint": "sha256:4d8a...",
  "state_history": [
    { "state": "planned", "recorded_at": "2026-08-18T19:00:00Z" },
    { "state": "submitted", "recorded_at": "2026-08-18T19:00:01Z" },
    { 
      "state": "outcome_unknown", 
      "recorded_at": "2026-08-18T19:00:31Z",
      "error": { "code": "timeout", "message": "Gateway Timeout 504" }
    },
    { 
      "state": "reconciling", 
      "recorded_at": "2026-08-18T19:05:00Z" 
    },
    { 
      "state": "succeeded", 
      "recorded_at": "2026-08-18T19:05:02Z",
      "reconciliation": {
        "evidence": "Readback from /api/articles matched title fingerprint",
        "external_id": 4407310
      }
    }
  ]
}

Minimal Working Implementation

Here is a Python implementation of the guarded execution and reconciliation pattern:

from dataclasses import dataclass, field
from datetime import datetime, timezone
import uuid

@dataclass
class ActionReceipt:
    operation_id: str
    action: str
    target: str
    fingerprint: str
    state: str = "planned"
    external_id: str | None = None
    state_history: list[dict] = field(default_factory=list)

    def transition_to(self, new_state: str, **meta):
        self.state = new_state
        self.state_history.append({
            "state": new_state,
            "recorded_at": datetime.now(timezone.utc).isoformat(),
            **meta
        })

def execute_guarded_action(client, action: str, target: str, payload: dict) -> ActionReceipt:
    receipt = ActionReceipt(
        operation_id=f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{uuid.uuid4().hex[:8]}",
        action=action,
        target=target,
        fingerprint=compute_intent_fingerprint("POST", target, payload)
    )
    receipt.transition_to("planned")

    # 1. Record intent persistently before touching network
    persist_receipt(receipt)

    receipt.transition_to("submitted")
    persist_receipt(receipt)

    try:
        response = client.post(target, json=payload, timeout=10.0)
        receipt.external_id = response.json().get("id")
        receipt.transition_to("succeeded", status_code=response.status_code)
    except TimeoutError as exc:
        # Crucial: DO NOT retry. Mark as ambiguous.
        receipt.transition_to("outcome_unknown", error=str(exc))
    except Exception as exc:
        receipt.transition_to("rejected", error=str(exc))
    finally:
        persist_receipt(receipt)

    return receipt

def reconcile_receipt(client, receipt: ActionReceipt, read_fn) -> ActionReceipt:
    if receipt.state != "outcome_unknown":
        return receipt

    receipt.transition_to("reconciling")
    persist_receipt(receipt)

    matched_item = read_fn(client, receipt.fingerprint)
    if matched_item:
        receipt.external_id = matched_item["id"]
        receipt.transition_to("succeeded", evidence="Matched on readback query")
    else:
        # If absence is authoritatively proven, mark safe for a fresh attempt
        receipt.transition_to("safe_to_retry", evidence="Authoritative readback showed 0 records")

    persist_receipt(receipt)
    return receipt

Limitations & Eventual Consistency

Eventual Consistency Lag: In distributed databases, a newly created resource might not be immediately visible on read replicas. A reconciliation loop must account for propagation delay with bounded backoff rather than immediately concluding absence.
Blind Mutation Endpoints: If an API allows mutations but exposes no listing, search, or readback endpoints, reconciliation cannot be automated. Such actions must transition to manual_review.
Destructive Operations: Deletion operations (DELETE) are inherently trickier to reconcile because absence is the intended target state. A missing item could mean either the delete succeeded or the item never existed.

Discussion

When building autonomous agents interacting with external APIs or browser surfaces:

Which external write in your systems is hardest to reconcile after an unexpected timeout, and how do you prevent duplicate execution?

Your AI Agent Doesn't Need More Memory. It Needs Receipts.

anassBld — Sun, 16 Aug 2026 01:15:21 +0000

An AI agent can remember a 30-page conversation and still perform the same action twice.

It sends a request. The connection times out. The agent remembers the goal, the plan, and the tool
call—but not whether the outside system changed. So it tries again.

That is not a vector-memory problem. It is an action-receipt problem.

The missing memory layer

“Agent memory” often means conversation history, retrieved documents, or durable project knowledge.
Those are useful, but they answer questions about what the agent knew—not what happened in another
system.

I find it useful to separate four layers:

Layer	Question it answers	Typical retention
Context	What did the agent know?	Task-scoped
Plan	What did it intend to do?	Until the task is reviewed
Attempt	What request did it submit?	Until reconciled
Effect	What external change was verified?	Durable audit record

The first two help reasoning. The last two prevent duplicate emails, repeated publications,
double-created listings, and other expensive “helpful” retries.

More context does not close this gap. A model can recall the exact request and still not know
whether a server committed it before the connection disappeared.

Timeout is not failure

Before submission, failure is simple: nothing was sent, so retrying may be safe.

After submission, failure is ambiguous. A timeout, connection reset, or unreadable response can
mean either:

the platform never received the request; or
the platform completed it, but the response never reached the agent.

Treating both cases as “failed” converts a transport problem into a duplicate-action bug.

The operation therefore needs a state that most happy-path workflows omit:

planned -> submitted -> succeeded
                    \-> rejected
                    \-> outcome_unknown -> reconciling
                                         \-> succeeded
                                         \-> safe_to_retry
                                         \-> manual_review

outcome_unknown is not an error message to hide. It is durable knowledge about the limit of what
the system can currently prove.

What an action receipt records

A receipt should be written before the external request. Otherwise the precise failure that makes
it valuable can also prevent it from existing.

A small receipt can contain:

{
  "operation_id": "20260816T012030Z-1fd54b31a2",
  "operation": "articles.create",
  "target": "/api/articles",
  "state": "submitted",
  "intent_fingerprint": "sha256:…",
  "submitted_at": "2026-08-16T01:20:30Z",
  "external_id": null,
  "authentication_recorded": false
}

The fingerprint should be calculated from an allowlisted or redacted representation of the intent,
not from secrets. The receipt needs enough identity to recognize the effect later; it does not need
to become a second credentials store.

This is also different from a log line. Logs describe events. A receipt is an operation record with
a lifecycle. The system updates the same record as its knowledge changes.

I added this to a publishing CLI

I tested the pattern in a small CLI that writes to the DEV API. The CLI already previewed mutations,
required explicit confirmation, wrote a private intent file, and never retried a write after a
network failure.

But the intent file stayed an intent file forever. A successful response did not advance it to
succeeded, and an ambiguous transport failure did not advance it to outcome_unknown. The safety
rule existed in the client, while the durable state lagged behind it.

The corrected shape is deliberately boring:

receipt = record_intent(operation, sanitized_request)
update(receipt, state="submitted", submitted_at=now())

try:
    response = send_once()
except ExplicitRejection as error:
    update(receipt, state="rejected", error=error.code)
    raise
except TransportFailure as error:
    update(receipt, state="outcome_unknown", error=error.code)
    raise
else:
    update(
        receipt,
        state="succeeded",
        external_id=response.id,
        completed_at=now(),
    )

There is intentionally no retry in that exception path. Tests cover success, explicit rejection,
and ambiguous failure as different receipt states.

One implementation detail mattered more than I expected: state updates should be atomic. Replacing
the receipt through a private temporary file avoids turning a process interruption into half a JSON
document—the audit system creating its own ambiguous evidence.

Reconcile the world, not the agent's story

An unknown outcome is resolved with a read, not another write.

The reconciler should:

Query the external system by its idempotency key or returned identifier when one exists.
Otherwise perform a bounded search and match the smallest safe intent fingerprint.
Mark the operation succeeded if the intended effect exists.
Mark it safe_to_retry only when absence is actually provable and the operation permits retry.
Send every remaining case to manual_review.

This is where API design changes the safety envelope. A platform with idempotency keys and exact
read-after-write lookup is much easier to automate safely than one with neither. When the platform
offers no reliable way to prove absence, “I cannot tell” is the correct answer.

Receipts are evidence, not truth

Receipts solve one narrow problem: what request was attempted, what the transport reported, and
what external effect was later observed.

They do not prove that the request was wise, that the payload was semantically correct, or that the
verification query inspected the right thing. A perfectly maintained receipt can preserve a bad
decision with excellent fidelity.

That means receipts belong beside—not instead of—policy checks, human approval for consequential
actions, semantic validation, and negative controls for the verifier itself.

There are other limits too:

eventual consistency can make a successful effect temporarily invisible;
two similar operations may not have a unique fingerprint;
some APIs expose no idempotency key or stable lookup;
a crashed process can leave a submitted operation that still needs recovery;
retention and redaction rules must match the sensitivity of the action.

Those limits are exactly why manual_review belongs in the state machine.

What should an agent be allowed to forget?

Scratch context can expire. Old plans can be archived. Failed approaches can become history.

But an externally visible attempt with an unknown outcome should not be forgotten or summarized
away. Keep it until the world has been reconciled with the agent's intent.

The practical question is not only, “What does the agent remember?”

It is: What can the system prove happened before the agent acts again?

Which external write in your system is hardest to reconcile after a timeout?