DEV Community: Likhan Siddiquee

Architectural Debt is the New Technical Debt

Likhan Siddiquee — Thu, 01 Oct 2026 11:03:29 +0000

Imagine a request to show payment status on an order page. An agent finds the order endpoint, adds a paymentStatus column to the orders table, copies a field from the billing response, and updates the UI. The tests pass. The ticket closes.

Which service owns the truth when a refund happens tomorrow?

If billing owns payments but orders stores a second status, someone now has to define how those values converge. A retry, an out-of-order event, or a partial failure can show a paid order as unpaid. The added code may be tidy. The decision about ownership is not.

That is architectural debt: the cost of a missing or compromised boundary, paid on every later change that crosses it. AI makes it easier to incur while making local code cleanup cheaper. The scarce skill is deciding what a system means and which part is allowed to say so.

The marginal cost of code fell, not the cost of change

Generating a handler, test, and migration takes less typing than it used to. An agent can also rewrite an awkward function, remove duplication, and fill in boilerplate quickly. Those are useful gains. They do not make the output free: someone still has to review behavior, migrate data, deploy the change, and support it when production disagrees with the test fixture.

Lint errors and duplicate code still matter, especially when they obscure a bug. But a clean lint report says nothing about whether paymentStatus belongs on an order. The local quality of the patch and the global shape of the system are different questions. Faster patching shifts attention toward the question that cannot be answered by rewriting a file.

I wrote about the velocity microphone: AI amplifies unclear intent and returns the consequences faster. Here the consequence is not a conspicuously broken function. It is a plausible new source of truth.

The easy path crosses the wrong boundary

An agent asked to make the order page show payment status will search for the code that renders the order page. The shortest path may be to extend the order model, because that is where the current request is being handled. No malicious reasoning is required. The task, the nearby code, and the tests all point at a local completion condition.

Then another feature reads orders.paymentStatus to decide whether to ship. A third updates it after a chargeback. Each change is defensible within its own ticket. Together they turn a display shortcut into a domain rule, and now neither orders nor billing can change its state model without coordinating with the other.

The same failure takes other forms: a shared database table becomes an unofficial integration API; a frontend duplicates an authorization rule; a "temporary" mapping layer becomes the place where two services disagree about customer identity. Generated code does not create these traps. It makes the easy path fast enough to take repeatedly before the coordination cost becomes visible.

Guard the contract before generating the patch

For the order-page request, I would first ask: is payment status a billing fact or an order fact? Suppose billing owns it. The order page can request a billing-owned view or consume a deliberately defined projection. If it caches a projection, the contract must name its source, update mechanism, failure behavior, and acceptable staleness. Orders should not become an independent authority for the same status.

That decision changes the agent's task. Instead of "add payment status to orders," the request becomes: "display billing's payment status on the order page; do not add a writable payment field to the orders model; specify what the page shows when billing is unavailable." The constraint is small enough to review and concrete enough to test. A contract test can catch an unauthorized write or a missing unavailable state. It cannot choose the domain owner on its own.

For any domain boundary, put the contract in the instructions the coding agent actually receives: AGENTS.md or copilot-instructions.md for repository-wide rules, or a scoped *.instructions.md for the code it governs. Name who owns each fact and state transition, how other domains may read it, which writes and dependencies are forbidden, and what happens when the owner is unavailable. Before editing, have the agent identify the relevant owners and explain how its proposed change crosses their boundary. If the instructions are missing or conflict with the code, or the request needs a new owner or exception, it should stop and ask the user to decide. It must not treat the nearest model as permission.

Instructions make a boundary visible; checks make violations harder to ship. Where possible, add dependency rules, schema ownership checks, and contract tests for the allowed exchange and its failure path. Have the agent run those checks and report what they cover. They cannot prove that the domain model is correct, so a person still has to judge new ownership and consistency tradeoffs.

This is the boundary guardian's work: name who owns a fact, define the permitted exchange, and make violations visible in scoped instructions, tests, APIs, and review. The goal is not to forbid every cross-service dependency. It is to give an agent a durable constraint it can follow and a check it cannot wave away, so the next change does not silently invent a second model.

The same reasoning applies to planning. I argued that sprint plans still point at an old bottleneck. When implementation is faster, it is tempting to queue more small features. Before calling one small, check whether it adds a new owner, projection, or consistency rule. A one-line field can be the most expensive part of the feature.

Code generation has changed what I can finish in an afternoon. It has not removed the need to decide where a fact belongs. If I skip that decision, faster implementation means I can accumulate architectural debt faster too.

Where have you seen a tidy local change create a second owner for the same fact? What boundary would have caught it?

https://www.likhansiddiquee.com/blog/architectural-debt-ai/

Task state is a call stack for agent work

Likhan Siddiquee — Mon, 31 Aug 2026 20:19:20 +0000

I was one hero image away from publishing a post about sprint planning. Generate it, wire the manifest, build the route. Three steps, then done.

I opened the image prompt for one last look and found it arguing with itself. It named colours in the same prompt that told the generator to avoid them. I asked why. That small question pulled us out of publishing and into an audit of every image instruction in the repository.

The corrected render arrived as a 1.63 MB PNG. I asked another small question: is that normal? Now we were comparing existing heroes, JPEG quality, chroma sampling, and edge artifacts. A second investigation had opened inside the first task.

The agent did not start either tangent. I did. On another day the agent spots the neighboring defect and asks whether to follow it. The risk is the same: the original task falls out of active context while one of us follows the more interesting question.

At the bottom of this stack, the post still needed its manifest entry, route build, and removal of a forward link to an unpublished part two.

We returned to all three because the task had a return address.

Task state is a call stack

A to-do list records what remains. A call stack records more: the current frame, its local variables, and the address where execution should return when a nested call finishes.

That is what .local/scratch/task-state.md does for my agent work.

In the analogy, the current frame is the immediate question. Its local variables are the working hypothesis, evidence, rejected paths, blockers, and decisions made so far. Its return address is the next step still waiting in the ledger.

Before either of us changes focus, the instruction tells the agent to checkpoint the ledger. The tangent becomes the current work while the unfinished task remains recorded beneath it. When the tangent closes, we update its result and resume the waiting next step.

In call-stack terms, the publishing task can be read like this:

publish sprint-planning post
  -> create hero
     -> I notice excluded colours inside the positive prompt
        -> we inspect the prompt rules
        -> return: corrected sidecar
     -> I question the 1.63 MB render
        -> we audit the export settings
        -> return: normalized hero
  -> wire manifest
  -> remove unpublished forward link
  -> build and inspect route shell

The stack did not stop us from going deep. It made the deep dive reversible.

The tangent can start on either side

Most descriptions of agent drift make the agent sound like the only source. It chases a neighboring bug, reads too many files, or turns a local fix into an architecture review.

I interrupt the plan too. I notice a strange output and ask how it happened. I challenge an assumption halfway through implementation. I open a related file while the agent is running and bring a new concern back into chat. Sometimes the side question is more useful than the task that
exposed it.

From the work's point of view, ownership of the tangent does not matter. Focus changed while a parent task remained unfinished. The parent needs a snapshot before the new question consumes the active context.

This is why task state has to be shared. It is not the agent's private plan, and it is not my private set of browser tabs. It is the handoff surface between our two attention streams.

The internal todo tracker is not enough

An agent's internal todo tracker is useful. It can decompose the requested work, mark steps in progress, and show whether the current turn is moving.

I do not treat it as durable task memory.

It belongs to the active agent session. It may not survive context compaction, a new chat, an editor restart, or a switch to another agent. More importantly, it cannot see a branch that starts in my head. If I inspect an image, question a design choice, or return after lunch with a different hypothesis, the internal plan does not know until I explain the change.

A todo item also tends to preserve the action while losing the state around it. "Normalize hero" does not say which settings were tested, why one candidate failed, what still needs visual judgment, or where publishing resumes afterward.

The local task-state file is visible to both of us. I can correct it. The agent can update it. A new session can read it before reconstructing the task from Git and a partial transcript. Because it lives in the workspace rather than the chat, the work does not depend on one session remaining alive.

How I keep the stack

I do not rely on remembering to take a snapshot once the tangent has become interesting. This repository's always-on context-persistence instructions carry the protocol. Copilot reads that file as repository guidance, so the checkpoint triggers arrive with each new session rather than remaining in the chat that may disappear.

The instruction is explicit:

For any non-trivial, multi-step task, ensure .local/scratch/task-state.md exists before the first edit. Create it only when absent.
If it already exists, read and reconcile it with the request and working tree. Preserve unfinished state; never truncate the file to start a new task.
Record the current focus, in-flight items and their status, the next step, open threads, and key findings.
Checkpoint before switching focus or deep-diving, when a new sub-issue appears, and after a meaningful step completes.
Re-read and reconcile the file when resuming.
When completed history makes the active file hard to scan, move it to .local/scratch/task-state-completed.md and promote any durable finding into tracked documentation in the same pass.

This is how I ensure snapshotting happens at the transition, not as cleanup after context is lost. It is still an instruction, not a transactional runtime guarantee. Its advantage is that the rule survives the session, the artifact is visible to both of us, and a missed checkpoint is reviewable.

The storage choice is part of the same instruction. This repository explicitly lists .local/ in .gitignore because the contents are local until promoted. A current hypothesis, unfinished frame, or rejected path should not be pushed to every contributor as project guidance.

Gitignored does not mean disposable. The devcontainer bind-mounts the repository workspace from the host. Rebuilding the container replaces the environment, not .local/scratch/task-state.md inside that workspace. The stack is still there when the new container opens.

I do not use VS Code chat memory as that recovery layer. A transcript may remain visible, but a new chat is not guaranteed to load it as working context; compaction can also remove the detail needed to resume. The task-state file has a stable path that the repository instruction tells the next session to read.

The ledger has no fixed schema. This run uses Current focus, Ledger, Chosen metadata, and Boundaries; older states also use Key findings, Remaining, and Gotchas. The headings follow the work.

There is no literal stack API or required Return field. I read in-progress as the top frame, a pending item plus its next step as the return address, and open threads and findings as the state needed to resume. Completing the tangent and returning to that pending item behaves like a pop. Finished history moves into task-state-completed.md; reusable findings are distilled into their tracked owner.

I ask the session what remains

Most of the time I do not open the task-state file myself. I ask the session:

What are my pending items?

The agent reads the ledger, reconciles it with the working tree, and gives me the unfinished items with their current status. I choose one. That item becomes the current work, and the session already has the findings, blockers, and next step recorded around it.

The question works in the same chat, after a context compaction, or in a new session because the answer comes from the workspace artifact. I am not asking the model to recall an old conversation. I am asking it to query shared state, then continue from the item I select.

This is a protocol, not a file format

Markdown under .local/ is how I implement the idea in these repositories. It is not the only way. An issue, worktree note, session database, or orchestration system can carry the same state.

The direction matters more than the storage choice:

The state is shared between the human and the agent.
It survives longer than one chat or internal plan.
A tangent records its parent return address before consuming the context.
Resume begins by loading that state, not reconstructing it from the current diff.
Completed frames leave the active stack.

Without those properties, changing the filename does not solve the handoff problem.

Shared memory makes curiosity affordable

I wrote about AI acting as a
velocity microphone: it amplifies unclear intent and returns the consequences faster. It also makes investigation cheap. A side question can become a twenty-file audit before either of us feels the cost.

I do not want to remove that curiosity from the workflow. I want a reliable way back.

The ledger preserves the parent task's return address through context compaction, agent changes, and my own detours.

The velocity microphone: AI amplifies unclear intent

Likhan Siddiquee — Mon, 24 Aug 2026 09:45:38 +0000

Twenty minutes prompting. Three days repairing.

That story is often used as proof that AI writes bad software.

Sometimes it does. Models invent APIs, miss edge cases, and make poor design choices.

But another failure is hiding inside that complaint: the classic tree-swing problem, compressed to machine speed.

The engineer knows they want a swing. The brief asks for a “dynamic, scalable outdoor kinetic relaxation mechanism.” The model fills the gaps with a plausible direction. Nobody challenges the assumption.

Twenty minutes later, the first real integration is also the first real test.

A hallucinated API is a model failure.

A coherent implementation of an unspoken assumption is an agreement failure.

AI did not remove requirements engineering. It removed the waiting that used to expose weak requirements before they became architecture.

The response is not one perfect prompt. It is a governance stack:

• Durable repository instructions that preserve architectural intent

• Specialized agent and workflow files that define the job

• Task briefs with boundaries and acceptance evidence

• Scoped tools and permissions that limit the blast radius

• Hooks, tests, lint, schemas, security scans, and CI

• Human review and release gates for the remaining uncertainty

Instructions steer.
Permissions constrain.
Checks reject.
Humans own the release.

AI is a velocity microphone. It amplifies the signal, the ambiguity, and the consequences.

I wrote about how to keep that speed useful:

https://www.likhansiddiquee.com/blog/velocity-microphone/

AgenticAI #SoftwareEngineering #AIGovernance #DeveloperExperience