DEV Community: Jeel Vankhede

A Verdict Is Not Evidence. Test Is Where I Learned the Difference.

Jeel Vankhede — Wed, 08 Jul 2026 18:28:04 +0000

The call-order change came back pass-with-risk. I read the recommendation, saw it had a name and a reason, and felt the task close.

Then I looked at the row under it. How was this verified: not run.

Nobody had run the queue. I had a label. I did not have proof.

This is Part 6 of The Contract

Think produced a brief. Plan produced a gate. Build executed inside it. Review scored every requirement against a verdict instead of an impression.

Review reads the diff and the plan and decides whether one satisfies the other. It does not run the queue. It cannot. Its whole job is judgment about what the code should do.

Test is where someone finally checks what the code actually does.

I had been treating those two as the same step. They are not.

Test asks one question, and a verdict is not the answer

For every active requirement, Test asks how it was verified. Command run, manual QA, or a comparison against known-good output. One of those three, or a written reason none of them ran.

Not a recommendation. Not a risk level. Evidence.

I built the matrix against the plan's requirements and filled in each row. Most had a command behind them. The call-order requirement had nothing. The cell read not run, and it sat directly below a pass-with-risk that already carried a name and a reason.

That name had almost been enough for me. A named risk feels handled. It is not. It is a risk with a label on it, waiting for someone to actually look.

So I ran the queue

Three notifications, all with a real reason to fire within the same tick. The scheduler picked them up and ordered them by priority instead of arrival.

Two landed in the sequence the requirement wanted. The third jumped ahead of a lower-priority notification that was still mid-processing.

The change worked almost every time. Under one timing condition, it did not.

That is the gap a verdict cannot see. Review had marked the requirement partial because the wording left the mechanism open. Running it found a real failure inside the mechanism the code had chosen. Same requirement, two different holes, and only one of them shows up when you execute.

The absence of an error is not evidence. I had to run the thing to learn the error was there.

The skipped check looked exactly like the ones that passed

Here is what unsettled me. If I had left that cell at not run, the matrix would have shown three green rows and one blank, and nothing about the blank would have raised its hand.

A skipped check is a risk hiding in sheep's clothing. It sits in the same table as the passing rows, formatted the same, quiet the same. Nobody flags it, because it does not look like a gap. It looks like the others.

Done and unverified render identically on the page. The only way to tell them apart is to do the check.

I almost deleted the failure after I fixed it

I fixed the ordering. Reran the check. It passed under the same timing condition that had broken it a minute earlier.

Then my hand went to the failure row to clear it. The bug was gone. Why keep a record of something that no longer happens?

I stopped, because the record was the point.

The matrix is not a snapshot of the final state. It is the evidence that the check ran at all. A row that only shows the passing rerun tells the next engineer nothing. A row that shows the failure, the fix, and the clean rerun tells them exactly where the edge was and how close the code came to crossing it.

I kept both rows. Deleting a fixed failure is not tidying up. It is erasing the only proof that anyone ever ran the check.

What Test actually gates

Test does not gate on whether the code works. It gates on whether every requirement has evidence behind it. Command, manual QA, output comparison, or an explicit skip with a reason, a risk, and an owner.

Not run is not a resting state. It resolves into evidence or into a named, owned risk, and until it does, the recommendation stays at hold.

Mine resolved. The recommendation came back ship, not because the first run was clean, but because the one requirement with a crack in it now had proof under the words instead of just the words.

A key takeaway:

This is not just a template for this article. It is the skill from the workflow I run after every review pass, before anything reaches Ship.

To summarise, test skill builds a verification matrix against every active requirement, runs configured commands where available, records manual QA and generated-output checks, and treats every skipped or not-run check as risk with a named owner rather than a silent pass. It writes a verify artifact that Ship can trust, and it will not let a recommendation past hold or hold-with-waiver until every row is accounted for.

Download it. Give it to your agent. Drop it into a task with an approved plan and a completed review. Watch it refuse to call something done until it can show you the evidence.

The verify artifact it produces is proof that Test ran inside the contract.

test.md on GitHub Gist

We shipped faster. The debt did too.

Jeel Vankhede — Sun, 05 Jul 2026 16:20:54 +0000

You open a file you have not touched in months and your first instinct is to read it like it belongs to someone else.

Not because it is broken. Not because the tests are failing. Just because you do not immediately know where its edges are.

You gotta believe me when I say I had that feeling recently, on a module I last touched roughly six months ago. The code ran. The logic held. But I had to re-read it like the way you re-read code you did not write: slowly, looking for the load-bearing pieces, rebuilding a picture of why it works before I could safely change it.

I had written most of it. "With help."

The AI agent had generated large sections. I had reviewed, adjusted, and approved the diffs. At the time, the pace felt like a genuine unlock. Six months later, the code felt like something from totally different era.

That feeling has a name. I just do not usually expect it from a six month old code.

The deferral deal was reasonable when debt was slow

Every team I have worked on had a version of the same arrangement. Not written anywhere, just understood. Debt built up, someone said "we should clean that up" before a release or during a quiet sprint, and a few of us did.

It worked because the debt built up at a pace we could outrun. I could hold that pace in my head. A feature took a week, maybe two, and "later" meant a real date I could picture, not a vague promise.

That is what calibration actually is. Not a policy. Not a perfect system. A feel for how much debt a stretch of work adds, built from doing the work slow enough to notice.

It only needs a name now because the pace it assumed is gone.

AI changed the input rate. Nothing else did.

The first time I generated a real feature with an agent, I was surprised by how much showed up in a short time. Not just the volume. The structure. It read like a focused week's work, done in a few hours.

I reviewed it, tested the critical paths, and shipped it. What I did not reckon with was the ratio: a few hours of review against a few days of generation, not several days of review against several days of authorship.

When I write slowly, I carry the context without trying to, I know the tradeoff I made and why, because I was the one standing in front of it. That is where ownership comes from. Not from reading the diff after.

When the agent writes it, that pacing disappears. The output arrives complete, and my review catches the obvious errors. What it cannot do is hand me the memory of a tradeoff I was never inside long enough to make myself.

It shipped like something I authored. It arrived like something I inherited.

Six months later, nobody on the team fully "knows" that module. It is not broken. It is just so dense in a way pre-AI code of the same age rarely was.

Six months now reads the way three years used to

This is not about "code quality" in the obvious sense. What I got back was honestly better than I could ever write; well-structured, function names held, nothing looked like a warning sign. Bad code announces itself. This did not.

I.e. The module was an integration with an external provider handling bank transactions. I followed their documentation closely. It started clean, one responsibility per file. Then requirements arrived faster than I could sit with any single one, and since most of it was AI-assisted, the smells piled up quietly under that pace. Six months in, when something broke, I could not find the reason by reading the code. The file no longer explained the behaviour it produced.

I was not holding the quality bar as tightly as I should have either. But that is the point, right? The pace made it easy not to notice I had stopped.

That kind of code used to take years to arrive at, turnover, drift, decisions made by people who had already left. I got there in six months. Not because I got worse at my job but because the code arrived faster than the ownership that comes with it.

Heuristic I keep coming back to: generation rate went up, review depth did not, so the gap between what shipped and what I actually understand widens quietly, because the code still looks fine.

That is the condition the old deferral deal was never built for.

Deferring to a later that does not arrive

The deferral strategy breaks at a specific point: when the cleanup sprint needed is larger than the capacity available for it.

That used to be a slow-moving threshold. A team could accrue meaningful debt over a year and still pay it down in a focused month. The math worked because the input rate and the cleanup rate were in the same range.

I did not clock this until I tried to schedule the cleanup for that six-month-old module and realised the sprint I would need did not fit anywhere on the roadmap. Not because the team was slow. Because the scope had outgrown what a sprint was ever built to absorb.

The comprehension side, the reading, the refactoring, the rebuilding of shared context, still runs at the pace I run at, because it is still my work to do. Nobody had documented why the decisions were made, so there was nothing to hand the agent that would have let it re-explain its own output. The understanding I needed had never been accumulated in the first place, and there was no shortcut back to it.

Six months of AI-assisted development had carried the density of what used to take two or three years to build up. The cleanup scope I was staring at was not what "we will get to it later" had ever budgeted for.

I do not think this is a failure on my part. The old calibration was reasonable. It was just built for a pace that no longer exists.

I do not have the answer. I have a question.

I am not sure what the new approach looks like.

I have gone looking. I have not found a team, a process, or a tool that has solved this completely, not the seeing part and not the deciding part, two different seams. Nothing tells you which modules have quietly lost their owner, or where the gap between what shipped and what anyone actually understands has drifted past what a sprint can close. And even when you can see it, there is no established way to decide what happens next that does not require a refactor window nobody can schedule.

I am working on an idea in this space. Pretty early to call it a solution. But before I shape it further, a question popped in my head: is the problem I am describing real for anyone, or just real for me?

If you have felt this: is the harder problem that you cannot see how much AI-generated debt you are carrying, or that you can see it but have no system for what to do next?

I wanna know which one.

Every Requirement Gets a Verdict. I Had Been Reviewing Without One.

Jeel Vankhede — Thu, 02 Jul 2026 18:15:19 +0000

You merge the PR. The build passes. The code does what you expected it to do. You move on.

That is review for most engineers. A final read. A feeling that things looked right before the branch closed.

I did it the same way for years.

Three phases had already run before this one. Think had scoped the work, Plan had written the requirements, Build had shipped a diff that matched the plan exactly. I trusted that the chain held. I had never actually checked.

Then I ran the Review phase, and checking turned out to mean something specific: not does this work, but does this requirement hold up, and what is my evidence.

I went in expecting to approve it or send it back. The phase gave me three answers instead: covered, partial, missing. I found out what they meant one requirement at a time, starting with the one I almost got wrong.

I had been giving impressions, not verdicts

The notification scheduler used a queue to manage dispatch. Every call to the external provider went through it. The provider was never exposed directly. The requirement said the provider must be notified. It was notified, exactly the way I had pictured it.

I almost called it covered and moved to the next line.

The Review phase stopped me there. But the requirement said must be notified, not how. The queue had introduced a call order and a timing the requirement never anticipated. Nothing was broken. Something had changed shape, quietly, and nobody had written that shape down.

I sat with that for longer than I expected to. Not because the code was wrong. Because I could not immediately tell you whether the change mattered.

The same pass gave the shim from Plan a different verdict on the same page: covered. Mapped to the requirement it existed to satisfy, no gap between what was promised and what was in the diff.

One requirement held exactly the shape it was given. The other had quietly grown a new one. Same review. Same pass. Two verdicts.

Partial is not a softer word for broken. It is the verdict for this much, no more, and here is exactly where it stops.

Naming the risk I almost skipped

A partial verdict did not resolve on its own. It forced a recommendation I had never had to give before: pass, pass-with-risk, or hold. The two options I knew, approve or send back, had no room for the case that actually mattered, the one where the code worked and the requirement was still uncertain.

I had to decide, in writing, whether the queue change mattered enough to hold the work. It did not feel small in the moment. The provider was being reached. The queue was deliberate architecture, not an accident I had stumbled into. But I could not confirm the call order and timing from the diff alone, and pretending I could would have been the same thing I used to do without a name for it.

I wrote it down as pass-with-risk. Not because the risk had gone away. Because I had looked at it directly instead of letting it pass quietly, the way every requirement before this phase had been allowed to.

Pass-with-risk is handing off the baton with the crack already named.

The contract was not three phases

Review is the first phase that looks backward and forward at the same time. Backward at everything Think, Plan, and Build produced. Forward at what Test will have to verify because Review could not finish the job alone.

"Looks good to me" was never a verdict. It was an impression wearing a verdict's clothes, and I had been handing those out for years without noticing the difference.

Covered. Partial. Missing.

I cannot unlearn that vocabulary now. The next time I review a diff without it, I will feel exactly what is missing, the way I never could before this phase existed.

Test runs next. It will find out whether pass-with-risk was the right call, or just a well-documented mistake.

A key takeaway:

This is not a template I built for this article. It is the skill I run after every plan and build pass.

The review skill inspects the actual diff against the brief, plan, and task artifacts, not against intent or memory. It maps every active requirement to covered, partial, or missing, runs a blocking pass and a non-blocking pass, and forces a recommendation of pass, pass-with-risk, or hold before Test is allowed to start.

Download it. Give it to your agent. Drop it into a task that already has a diff and an approved plan. Watch it refuse to call something covered until the evidence says so.

The review artifact it generates is proof that the diff was actually checked against the contract, not just read.

review.md on GitHub Gist

The Agent Did Not Drift. I Did.

Jeel Vankhede — Mon, 29 Jun 2026 14:21:37 +0000

The agent paused. It was waiting for me. I was not used to that.

Every AI tool I had worked with before would fill the gap. Ask it to implement a feature and it would implement the feature, then the next logical thing, then the thing after that. You would come back to a diff three times larger than what you asked for. Confident. Finished. Sometimes wrong.

Build did not do that.

It executed Phase 1. It stopped.

I reviewed. I approved. It executed Phase 2. It stopped again.

I kept expecting it to continue. It never did.

That patience was not a limitation. It was the contract working.

The work that earns the right to be boring

This is Part 4 of The Contract. If you are starting here: Think produced a brief, Plan produced an approved sequence, and Build is where that sequence runs.

Every frontend codebase has a version of this problem. One notification on launch. Then two. Then three conditions deciding which one to show. Nobody centralises it because it is never urgent enough. Until it is.

I had let mine reach that point.

Background items resolved on app launch. Each one could trigger a notification. The logic deciding which notification to show lived at each call site. No scheduler. No priority. Just conditions stacked on conditions, each one unaware of the others. They started colliding.

I wrote a brief. I wrote a plan.

Five phases. Three to consolidate everything under one scheduler and build the queue. One to wire it into the launch sequence. One to clean up.

Brief done. Plan approved.

By the time Build started, every structural decision had already been made. Build did not need to think. It only needed to execute.

Build has entry conditions.

It checks the branch state before touching a file. It verifies the plan artifact is approved. If the branch is wrong, it stops. If scope has expanded beyond what the plan defined, it stops. Build does not interpret intent. It verifies state, then executes.

Phase 1 executed. Scheduler in place. Files where the plan said they would be. I reviewed it and approved Phase 2.

Phase 2. Phase 3. Each one scoped, reviewable, testable on its own.

That is what two phases of upstream work buys. Not code that works. Code that arrives narrow enough to be understood before it is approved.

That narrowness is what let me catch what was coming.

Build did exactly what I asked

Phase 4 landed.

The queue was wired into the launch sequence. First run: correct. The scheduler picked up the items, ordered them, surfaced the right notification.

Second run: nothing.

The queue never reset between sessions. Items were scheduled once and never cleared. The scheduler treated the queue as durable when the system treated each session as disposable.

The brief described the scheduling logic, the priority ordering, the collision rules. It did not say anything about queue lifetime. It did not say when to flush. It did not say what a session boundary meant to the scheduler.

Build implemented exactly what the artifact said. When the artifact was silent, Build stayed silent too.

Donald Knuth had this right: "Computers are good at following instructions, but not at reading your mind."

I went back to the brief and read it the way Build had read it. The flush condition was not there. Not buried or ambiguous. Just absent. I had written around the scheduler lifecycle without ever writing about it. In my head the reset was obvious. In the artifact it did not exist. The brief was missing the one line that would have made Phase 4 correct on the second run.

The gap was not in the code. The gap was in what I had decided was too obvious to write down.

The agent did not drift. I did.

The gate that made the gap catchable

The moment I found it, Phase 5 had not started.

Nothing downstream had been built on top of the broken assumption. That is not luck. That is the architecture of the workflow.

Build waits between phases because a human checking partial output mid-sequence costs one review. Finding the same problem after Phase 5 costs five phases of rework.

The exit condition is not delivery. It is confirmation. Without that gate, Build is just a slower way to get a large diff.

I added the flush condition to the brief. I updated the plan. The phase re-executed. Phase 5 ran clean.

One gap. Caught at the right moment. Without a cycle of iterations to find it.

The brief is the contract

Build executes what exists in the artifact. No more. No less.

I had expected Build to catch my oversight. That expectation was wrong. The workflow was designed to make it wrong.

Build is not a safety net for an incomplete brief. It is a precise executor of an approved one. When the brief is honest, Build produces exactly what I imagined. When the brief has a gap, Build produces exactly that too.

The five phases landed at roughly 95% of what I intended.

That number felt high at first. Then I looked at where the 5% came from.

It came from me. Every time. A brief assumption that did not make it into the artifact. A detail that seemed too obvious to write. An edge case I held in my head instead of the plan.

Build did not miss those things. I never gave them to Build.

The workflow did not fail. It showed me everything I had decided was too obvious to write down.

That is the most honest thing a tool has ever told me.

What comes next

Build closes with a task artifact.

Every changed file is recorded. Every check that ran is recorded. Every check that did not run is recorded with a reason.

Review does not start with the code. It starts with that artifact. The question Review asks is not whether Build made a mistake. It is whether what Build executed was actually what the plan intended.

A key takeaway:

This is not a template I built for this article. It is the skill I run after every feature plan.

The build skill executes exactly one approved plan phase at a time, preserves unrelated changes, inspects branch and repo state before edits, and records every changed file with manifest IDs and command evidence. It stops when scope expands. It waits when branch state is wrong. It produces a task artifact Review can trace back to the plan.

Download it. Give it to your agent. Drop it into a task that already has an approved brief and plan. Watch it pause instead of fill in the gaps.

The task artifact it generates is proof that Build ran inside the contract.

build.md on GitHub Gist

The Plan Blocked Me. That Was the Correct Outcome.

Jeel Vankhede — Tue, 23 Jun 2026 04:05:24 +0000

The brief was approved. Scope defined, questions closed, acceptance criteria written. The obvious move was to start building.

I ran the Plan phase first.

Planning and the Plan phase are not the same thing.

Planning produces direction. The Plan phase produces a gate.

Every engineer plans. Sprint boards. Jira tickets. A rough sequence before a large refactor starts. It works well enough because a human engineer carries what the plan does not say. They know what they did not write down.

An agent does not. An agent fills the gaps with its best guess. That is not inefficiency. It is drift. I covered what drift costs in the last part of this series.

The Plan phase has one property that a sprint board does not: refusal conditions.

A plan that cannot refuse you is documentation. A plan with refusal conditions is a gate.

Nobody brings materials to a construction site and figures out the building as they go. There is a blueprint first. Then an estimate. The estimate is not the slow part. Finding out mid-build that a wall cannot go there is the slow part.

The brief is the blueprint. The Plan phase is the estimate.

The impact map found what the brief described in one line

The refactor target was a god class. It owned too much. The brief said split it.

Most codebases have a version of this. A module that owns too much and the team has learned to work around. The brief names it in one line and moves on. The impact map cannot.

It found that the god class held the payload formatting logic. Every notification the system sent passed through it before leaving the application boundary. Split it wrong and the notification contract breaks. Which phase owns that during the transition?

I thought the brief had answered that. It had not.

The impact map could not answer it either. That required the risk register.

The plan blocked. That was correct.

The risk register stopped me at a question I had not prepared for.

The payload format was a contract with the external notification provider. The provider expected specific field names and structure. It did not return an error when that structure changed. It silently rejected the payload. No exception. The only evidence would come downstream, weeks later, when someone noticed the silence.

That kind of failure is a time bomb.

There was no mitigation in the current plan. The plan blocked.

My first instinct was to push through. Grant myself the waiver. Flag it low risk. Sort it out during Build. That is the exact moment the Plan phase exists to intercept. Not because the risk was catastrophic. Because the question was unanswered, and an unanswered question does not disappear. It travels into Build and becomes the agent's problem.

I had always sorted things like this mid-build. This time the plan would not move until I had the answer.

That cost time I had not budgeted. It cost less than tearing down a wall mid-build.

So I answered it.

The decision was made at plan time, not build time

I made the call. Not automatically. The simpler path was to move everything in one phase. But one ordering changed the external interface before the replacement was verified. The other preserved the notification contract through the transition and required a human to confirm the payload format before the agent could proceed.

No code was written. I made a sequencing decision. The agent would follow it.

A human engineer would have caught this mid-build. Professional instinct. Write "migrate notification dispatch" as a task and the agent migrates it. It does not know the field names are a contract. It does not know silent rejection is the failure mode. It does not know to pause before continuing.

The god class was specific to this refactor. The problem it exposed was not. Something will always look safe to move. What makes it unsafe is external, invisible to a scan, and silent when it breaks.

Build owns code. Plan owns sequencing.

The plan was signed. That was not the end.

Think told me what to build. Plan told me in what order. Those are not the same document and they are not the same decision.

That is not a handoff. That is a gate.

Build started with a plan the agent could not diverge from. Whether the plan was precise enough was a question only Build could answer. That is the next part.

A key takeaway:

This is not a template I built for this article. It is the skill that I run for my plans.

The plan skill prepares an impact map, risk registers, phases and verification gates. It enforces that all risks are known and user is acknowledged before Build begins and produces the plan as a versioned artifact.

Use it in the sequence to the Think. Once the brief is generated, you prepare a plan and read how it differs from the regular plans that AI makes.

plan.md on GitHub Gist

An AI Agent Is a Hammer. The Think Phase Is Where You Aim It.

Jeel Vankhede — Fri, 19 Jun 2026 14:16:33 +0000

The agent runs. The code appears. The feature is not what I wanted.

Not because the model was wrong. Because I was vague.

Speed Was Never the Moat

Before AI could write a single line of code, the best engineers were not the fastest ones.

They were the ones who thought first.

The engineer who paused long enough to understand the system, the constraints, the consequences, consistently shipped better work than the engineer who started typing first.

Speed was the byproduct of clarity.

The ones who skipped the thinking phase did not save time. They silently redirected it into debugging, rework, and escalations nobody had scheduled for.

AI did not change this. It amplified it.

A senior once taught me: Every complex task started with pseudocode that never shipped. By the time coding started, I had already solved the problem I needed to build. Those documents were never the output. The preparation was.

The discipline that managed it was never new.

The Architect Did Not Build. The Architect Made Building Possible.

I picked up a clean refactor not long ago. A couple of backend endpoints that had become legacy over time, god classes built up through delayed maintenance. The project already had rules and instructions in place. Patterns documented, constraints named, architectural decisions recorded.

The refactor ran clean. Manual testing surfaced one issue: a status mismatch on a response from a newly introduced feature that was not yet documented in the code. That was the full extent of the friction.

The difference between that refactor and the React Native incident I described in the previous article, where the agent implemented a plan correctly and the plan itself was wrong, was not capability. It was context. One project had a contract. The other did not.

Every project that shipped well had someone building that context before a decision was locked in. Not the fastest coder. The one who understood the system as a living structure: existing patterns, load-bearing decisions already made, consequences that travel downstream.

The right moment to catch a structural mistake is before the first line of code. Not in a review after the tenth.

That part has a name in this workflow, the first step: Think.

Capability Is Not the Bottleneck. Ambiguity Is.

The agent is not too slow. It is not too limited. It does not lack capability.

It lacks direction.

I noticed the pattern on the tasks that touch the most files. Performance optimisation. A third-party service integration that reflects behaviour across several endpoints. Underperforming routes moved to a Redis cache. The agent did not struggle with any of them. It moved confidently, thoroughly, and in the wrong direction.

Feed an AI agent a vague prompt and it does not return silence. It returns something confident, coherent, and pointed at the wrong target. The agent fills ambiguity with inference. It makes decisions I did not know I was delegating. It assumes the shape of the feature from the words I chose, not from the system I built.

The gap is not between what the agent knows and what I needed. The gap is between what the agent received and what I actually meant.

The interesting question is not "can the agent write this code?" The better question is "have I given the agent something precise enough that it cannot misread the direction?"

Those are not the same question. Most engineers answer the first one and wonder where the week went.

The Architect Persona: Gather Direction, Not Just Code

At the Think phase, the agent takes on a specific role.

Not implementer. Architect.

Its job is not to generate. Its job is to understand.

It reads the codebase. It maps what exists. It surfaces existing patterns so the feature does not reinvent what the system already decided. It separates what I stated from what the codebase implies. It flags what is known and what is not.

It does not proceed on a guess when a decision belongs to me.

By the time Think ends, the agent has not written a single line of production code.

The architect persona is not a mindset I sustain through discipline. It is a structured phase, and it runs as a skill.

What it produces is the brief.

The Brief Is How I Aim the Hammer

The brief is the first artifact of this workflow.

It is not a ticket. It is not a prompt. It is not a description of what I want.

It is a specification of direction, written precisely enough that the agent cannot misread it.

What goes in it.

Intent. Not "add a filter to the dashboard." The outcome the user achieves and the system condition that changes. Vague intent is how the agent builds the right-looking wrong thing.

Constraints. Technical limits and architectural decisions already made upstream. They define the edge of the work before it begins.

What the codebase already knows. If the pattern exists somewhere in the system, the brief names it. The agent does not invent a solution the codebase already has.

Explicit unknowns. Two kinds: assumptions the agent can safely proceed on, and open questions that belong to me, marked blocking or non-blocking. The agent does not guess either way. It surfaces them and waits.

Definition of done. Not a feeling. A condition the agent can verify.

Hammer the exact spot.

A craftsman strikes metal at precisely the right point.

Not harder. Not faster. Exact.

The masterpiece is not a product of force. It is a product of aim.

That is what the brief produces. A single concentrated point of direction. The Think phase does not add steps to the workflow. It removes the steps that appear later when direction was absent.

It hammers the exact spot.

Direction Is Not the Route

The brief tells the agent where to aim. It does not tell the agent the order of the blows.

That belongs to the Plan phase.

The Think phase does not complete when I feel ready. It completes when the brief is specific enough that an agent working from it cannot misread the direction.

That is a higher bar than it sounds. It is also the bar the Plan phase builds on.

A key takeaway:

This is not a template I built for this article. It is the skill I run at the start of every feature.

The think skill classifies the task, separates explicit from implicit requirements, and marks open questions as blocking or non-blocking. It enforces an exit condition before Plan begins and produces the brief as a versioned artifact.

Download it, Give it to your agent, Drop it into your first task. Read what it produces before the agent continues.

The brief it generates is proof that Think ran.

think.md on GitHub Gist

The Agent Did Exactly What I Asked And That Was the Problem.

Jeel Vankhede — Thu, 18 Jun 2026 13:45:24 +0000

Back in 2022, working with an AI coding assistant meant keeping a browser tab open.

You typed a question. You got a code block. You figured out where it belonged. That was it.

The suggestions were useful in the way a dictionary is useful. Technically correct. Completely unaware of what you were actually building. You stitched the outputs together yourself and moved on.

The context problem started to close

Then came late 2024.

MCPs arrived. Context pipelines. Codebase-aware agents that could read your patterns, follow your naming conventions, understand the domain you were working in. The agent was not just answering questions anymore. It knew the project, the structure, the terminology you had already established.

This was a genuine step change. Not hype.

But something still did not work on complex tasks.

Single-feature work was fine. Isolated changes landed cleanly. When the scope crossed modules, crossed boundaries, crossed the full surface area of a codebase, the agent started drifting. It solved the visible problem and left behind the invisible ones.

I noticed this. I assumed I needed a better plan.

I was right about that. I was wrong about almost everything else.

The agent did exactly what I asked. That was the problem.

The task: a global event mechanism and component communication layer across an entire React Native application.

This was not a small task. Done by hand, with a focused engineer, it would take two weeks minimum. The agent understood the domain well. I handed it the work, expecting two weeks to become two days.

I created a plan. I reviewed it. I approved it.

Neither the agent nor I noticed what the plan did not cover: conditionally-loaded passive components that lived outside the event mitigation scope. No impact map. No blast radius analysis. No verification scenarios. A proper engineering sprint would have treated this as a one to two sprint production artifact. We treated it as a chat output.

The agent implemented the approved plan. Correctly.

That sentence should sound like a success. It is not.

It looked finished. It was not.

Passive and conditional components were outside the event mitigation scope entirely. State changes in those sections did not render correctly. The UI broke in places no one had thought to check, which meant I only found them by using the parts of the app the plan had quietly skipped.

The duplication was worse because it was invisible. Event handling had been wired in across several locations. I only caught it after adding console logs to trace the event flow and watching the same event fire more than once.

The third failure was different. The agent used a combination of Context and Redux for event-driven architecture. It added boilerplate that was never asked for, invented an implementation pattern that was not in scope, not in the plan, and not something I wanted. I had to go back to plain text, explain how it should actually work, and ask it to correct.

That raised a question I kept coming back to: why would AI do something not asked, not in scope?

The answer is not a defect. It is the absence of a constraint. There was no rule saying otherwise. The agent filled the gap with its best guess. The best guess was wrong.

No tracking. No checkpoints. No floor.

No task tracking existed. No verification log. No regression checkpoints.

Each observation I fed back got implemented immediately.

Code layered on top of code. The chat thread grew too long.

I summarised and started a new chat. Picked up from there.

It worked briefly. Then introduced new issues.

The pattern kept repeating.

By day three, the implementation was 70-75% aligned with the original plan. No clear record of what had been verified, what had not, and what still needed a human decision. Just a long sequence of chat messages and fragile code.

I made it work by the end of day three. Satisfactory, not clean.

Coding was never the problem

I went in assuming the failures would be about code quality. Complex logic, edge cases, missed conditions.

It was not that.

The agent had good context. It could write the code. What it could not do is decide what the work actually is. That is not a tool limitation. It is a role boundary.

Not during the process. Not at the end. At the beginning.

During the process, human review catches mistakes after they happen. At the beginning, human judgment defines the surface area before anything starts.

That realization sent me looking. After three days, I researched existing solutions and tested a few. They work. They are well thought through. But they are built for the general case. To use them seriously, you adapt them to your stack, your conventions, your project's specific constraints. That gap is the part nobody packages for you.

I did not want to recommend something I had not built and broken and rebuilt. I did not want to write about a workflow I had read about rather than lived. I was not sure the workflow would hold.

The thing I was missing was not a better tool. It was a contract.

Seven phases. A human approves every handoff before the next phase begins.

That is what the next part covers.

Open the PR your reviewer has not met yet

Jeel Vankhede — Thu, 18 Jun 2026 13:41:35 +0000

I got a PR to review recently. Large diff, AI-assisted, touching a module three other features depended on. The description was one sentence. It named the file, not the reason.

I spent fifteen minutes just mapping the change before I could start reviewing. What the intent was. Where the risk was. Which files mattered and which were noise.

Somewhere in the middle of that fifteen minutes, I thought: I have done this to someone else.

The author forgets what the reviewer does not know

When you write the code, you carry everything.

You know why the module was split. You know what you tried before landing here. You know which section you shipped with a quiet doubt. You know the edge case that is technically handled but not properly tested.

Then you open the PR.

And you write the description from that place. From inside the full context, for the version of you who already knows. Not for the reviewer who is about to walk in without any of it.

"Refactored service layer."

"Updated config handling."

"Fixed issue with auth module."

These are descriptions written from memory, not for someone without it.

AI widened the gap before I noticed

There is a specific unease I have felt looking at my own PRs a couple of days after raising them.

The code is fine. The tests pass. But I cannot reconstruct why I made the choices I made. The work was AI-assisted, the diff was large, and I had moved fast. Moving fast and understanding deeply are not the same thing.

I opened one of those PRs recently. A refactoring pass. I tried to read it as a reviewer. I had a question I could not answer from the description. The answer existed. It was in my head when I wrote the code. It never made it into the PR.

That was the moment I realized the description was not a summary. It was a test.

Write it for the version of you who will review this in three days

That realization changed how I write descriptions.

Not a template first. A question first: if I came back to this PR in three days knowing nothing, what would I need to read before opening the diff?

I sat with that question long enough to realize I needed a structure. Not something I could skip when moving fast. A concrete template I would follow before any non-trivial PR opens. I built it, tested it across refactoring passes, AI-assisted features, and larger architectural changes, and refined it until it held.

It has six parts.

Intent - not what changed, but why this PR exists and what problem it is solving. One paragraph. If you cannot write it clearly, stop. The PR is not ready to open.

Major changes - the decisions that touch architecture, existing behavior, or anything a downstream system depends on. This is where the reviewer needs to slow down.

Minor changes - the cleanup, the renames, the noise. Named separately, so they do not sit next to structural changes and get equal weight.

Impact - what features, modules, or systems this PR touches. The blast radius, stated plainly. Not documentation. A map.

Evidence - what was run, what was walked through manually, what coverage looked like. Not to satisfy a process. Proof that the author did the work before asking someone else to do it.

And the one most descriptions never reach: what I was uncertain about.

Naming uncertainty is not weakness. It is direction.

When something works but I cannot fully explain why, I say so. Directly, in the description.

For the reviewer, it is a targeting signal. They know where to read closely and where to move. Without it, they distribute attention evenly across a diff that does not deserve even attention.

Writing it is a checkpoint. If I cannot name what I am uncertain about, I have not thought carefully enough about my own code. That line has stopped me from opening PRs that were not ready.

The description is not the last step before review. It is the last step before I know whether the PR should open at all.

The reviewer who opens this has not met your code yet

When I compare the PRs I was proud of shipping against the ones that came back with questions, the difference is rarely the code.

It is the description.

A reviewer who understands your intent from the first read spends their time on the hard questions. A reviewer who has to reconstruct your intent spends it on the easy ones. Asking what things are instead of whether they are right.

Part 1 of this series argues the reviewer's side of the same problem. If you arrived here first, it is worth the detour. The argument there: reviewers now need to look past surface correctness and find intent. But intent does not appear on its own. Someone has to put it there before the review begins.

Write it for the reviewer who has not met your code yet.

Write it as if you will not be there to answer questions.

Write it as if the next person to read it is you, three days from now, with no memory of writing it.

If it holds up, the PR is ready.

Review the code that does not exist yet

Jeel Vankhede — Thu, 18 Jun 2026 13:40:42 +0000

I have reviewed code for years, and for most of that time the habit was simple. Open the diff. Read every line. Find what is wrong. It worked, and it worked for a boring reason: the diffs were small because writing code by hand is slow.

The diffs are not small anymore.

A pull request now arrives with twenty files in it, built in an afternoon, more code than I could have written by hand in a week. The old habit does not fit a change that size. It bends, then it breaks. So I had to ask a question I had spent years quietly avoiding.

What is a code review actually for?

The first thing I lost was the point

Few years ago, I was the senior reviewer on a small team. I took the role seriously. Maybe too seriously.

I opened each pull request hunting for faults. Indentation. Naming. A function that could be three lines shorter. A pattern we had agreed not to use. I found them. I was good at finding them. It felt like the job. Every comment was proof that I had been paying attention.

One day I left seventeen comments on a frontend pull request.

It was a CSS-heavy change, and CSS changes are hard to review on a diff. The developer had not followed the UI design standards we had set as a team. Almost none of them. So I went through it line by line and marked every single thing I could find. I sent it back.

I felt like a jerk afterward. But I also thought I had done the right thing.

Then I looked at what I had actually been reviewing.

I had read every line. I had not read the work.

The developer had built exactly what was asked. The feature worked. It was a clear, self-contained piece of UI. And I had spent the entire review arguing with the formatting, as if the formatting were the thing we shipped to users.

That is the day I started reviewing code for a different thing. Not for what it does the moment it lands. For what someone will do to it next.

This is not an argument for shipping mess. I still send back work that buries its intent under careless code, because code that is hard to understand is hard to change, and hard to change is where the real cost lives. The difference is that I keep room for an exception now. I do not treat every rule as a wall I am paid to defend.

A rule is a tool for protecting intent. When I started treating the rule as the point, I forgot what it was protecting.

I had been reviewing the rules. I had stopped reviewing the work.

Then the diffs got faster than I could read

For a long time that lesson stayed quiet. Useful, but never urgent.

Most pull requests were small, because authoring was slow, and a reviewer could keep pace with an author without much strain. One person wrote for a day, another read for an hour, and the arithmetic worked. The whole practice of review was built on that arithmetic.

Then people started building with AI.

Now a change lands with twenty files. Different layers, different concerns, all in one push, all produced faster than I have ever produced anything in my life. And my first thought is almost always the same.

This is over-engineered.

Sometimes it is. Often it is not. The instinct fires not because I have judged the design, but because the sheer size of the thing is unfamiliar, and unfamiliar reads as wrong. The honest problem is mine. I could never have written that much code in a day. Reviewing it in a day was the part that unsettled me most.

The bottleneck moved.

AI made writing code cheap. It did not make reviewing it cheap.

Authoring used to be the slow and expensive step, and review was the quick sanity check at the end. That order has flipped. The code now arrives at almost no cost. The judgment about whether the code is right costs exactly what it always did, because judgment was never the part AI made faster.

The bottleneck did not disappear. It moved onto my desk.

So I changed what I look for first

If I cannot read twenty files the way I read two, then reading every line first is the wrong opening move. It is slow. Worse than slow, it is misaimed. It spends my sharpest attention on the smallest things, early, while the largest things wait, unread.

So I stopped starting with the code.

I start with intent. What is this change trying to do, and does the shape of it match that goal? Does the structure tell the same story the description promised? Only after those questions do I care how any individual line is written.

This is what I mean by reviewing the code that does not exist yet.

The diff in front of me is temporary. It is the least permanent thing in the whole exchange. Someone will change it in six months. Someone will debug it at two in the morning with half the context I have right now. Someone will push it past the scale the author ever imagined, and watch it fail in a way nobody designed for.

Those people are who the review is really for. Not the author, who already understands the change. Not me, who will forget it by next week. The stranger who inherits it.

The diff is what changed. The future is what I am approving.

The order is the method

Over time my questions settled into an order, and the order turned out to be the whole point. It is not a list to tick off until every box is full. It is a path, and most of it happens before I judge a single line.

It runs like this.

What is this trying to do? → How did they solve it, and would I have solved it differently? → What trade-offs or unknowns are sitting in plain sight? → Does this actually improve the thing, or is it added weight, a time bomb waiting for the day nobody is watching? → Am I sure?

Each question guards against a different failure.

The first keeps me from reviewing a change I do not understand. The second keeps me honest about the difference between a real problem and my personal taste. The third is where most of the danger hides, because the dangerous parts of a change are rarely the loud ones. The fourth is the one that only gets answered in production, usually later than you wanted. And the last question, am I sure, is the one I added for myself, because the worst approvals I have given were the confident ones.

Only after all of that do I open the files and read them line by line, with no mercy.

Look at where the strict part lives. At the very end.

Everything before it is about understanding the work and arguing with my own judgment. The line-level pass is not the review. It is the last step of the review, and it only earns its place once the rest has cleared.

You earn the right to nitpick. You do not start there.

This is not permission to ship slop

I can hear the objection, because I would raise it myself. Does intent-first mean a lower bar? Does it mean waving through sloppy code as long as the idea behind it is clear enough?

No.

The strict pass still happens. It happens last instead of first, but it happens, and nothing on the list above is a substitute for it. Intent-first is not standards-free. It is the same standards in a better order.

And there is a newer risk that makes the order matter more, not less.

Volume hides intent.

A twenty-file change can be correct in every single file and still be dangerous, because no one person can hold the whole of it in their head at once. The failure is not in any one line. It lives in the space between the files, in an assumption made in one place and quietly broken in another.

About nine months ago a pull request landed on my desk with forty-five files in it. I was lenient. I skimmed the parts that looked safe, approved what looked obvious, and moved on.

Six months later the APIs started creating duplicate transactions in production. We could not find the root cause. The file at the center of the problem had grown to over five thousand lines of code, and the issue was buried inside of it.

It took a long time to dig out. That change had looked fine in every file I checked. I had just never asked whether it was wise.

Reading for intent is how I catch that before it merges. A checklist cannot — it looks at each file alone.

A checklist can tell me the code is correct. It cannot tell me the code is wise.

The fear I started this with never left me. I have just stopped fighting it, and started letting it sharpen the right questions.

I did not learn to read faster. I learned to read in the right order.

What I actually approve

This is what I think a review is.

I am not the spell-checker. I am not the gate that catches a missing semicolon or an unused import. I am the person asking what this change will do to whoever inherits it, long after the author and I have both moved on.

That question works at every level of experience, because it is a question and not a rule. A new engineer can ask it on their very first review. A senior engineer asks it on their thousandth. Nobody is too junior to wonder what happens to this code in a year. Seniority does not exempt you from the question.

And it has a limit I have started to feel.

A reviewer can only do so much when the pull request is fighting them. If the intent is buried, if twenty files arrive with no story to tie them together, if the risky change is hidden in the middle of a dozen safe ones, then no amount of patient reading will rescue the review. The reader cannot supply a clarity the author refused to provide.

Which means half of this problem was never the reviewer's at all. It belongs to the person opening the pull request. That is the other half of the story, and it deserves its own piece.

Review is not about the code in front of you. It is about the code that comes after.

Most Engineers Use AI. Few Engineer With It.

Jeel Vankhede — Wed, 17 Jun 2026 23:25:52 +0000

Most software engineers I know use AI in some form now.

Maybe it is for debugging, boilerplate, tests, docs, SQL queries, shell commands, or quick code reviews. Some use it daily. Some use it quietly. Even the skeptical ones have probably pasted a confusing stack trace into a chat window once.

So I do not think the interesting question is:

“Do engineers use AI?”

The better question is:

“Has AI changed how they engineer?”

Because those are not the same thing.

Using AI is easy.

Engineering with AI is much harder.

The hard part was not code generation

I noticed this while using AI around real repository tasks where a wrong change was not just “bad output”; it could break structure, tests, naming, or future maintainability.

The code generation part was easy. A broad prompt could produce a lot of code quickly. Sometimes the output even looked clean at first glance.

But the useful results came only when I had already done the boring engineering work: define the requirement, limit the scope, explain constraints, and decide how I would verify the change.

The hard part was not asking AI to write code.

The hard part was giving enough context without dumping everything into the prompt. It was making the task small enough. It was asking for tradeoffs before implementation. It was reviewing the output without getting impressed by clean formatting.

Most importantly, it was checking whether the solution actually belonged in the system.

That changed how I looked at AI-assisted development.

Prompting was not the real skill.

Shaping the work was.

AI makes output faster, not verification stronger

There is nothing wrong with using AI for small tasks.

I use it for debugging direction, naming, boilerplate, test ideas, documentation drafts, and exploring unfamiliar code. Those are useful tasks. They reduce friction.

But the risk starts when faster output gets mistaken for better engineering.

AI can generate code quickly. It can produce clean-looking functions, structured files, confident explanations, and reasonable test cases. But it does not automatically know whether the change fits your product, your architecture, your constraints, or your long-term maintenance cost.

That part is still engineering work.

The problem is not simply that AI may produce bad code. Engineers already deal with bad code from humans, libraries, tutorials, Stack Overflow answers, and their own tired brains.

The bigger problem is that AI increases the speed of output without increasing the quality of verification.

If code becomes faster to generate, unclear requirements become more expensive. Weak review becomes more dangerous. Missing tests become more painful. Poor architecture becomes easier to copy and harder to undo.

AI does not automatically improve engineering.

It amplifies the engineering loop that already exists.

Think twice, code once

AI makes it easier to produce code before we have fully understood the problem.

That is useful when the task is clear.

It is dangerous when the task is vague.

If the requirement is unclear, AI will still produce something. If the architecture is messy, AI will still copy the mess. If the engineer cannot review the output properly, speed becomes risk.

This is why I think “AI will replace engineers” is the least useful version of the conversation.

A better question is:

“What parts of engineering become more important when code becomes cheaper to generate?”

My answer is: thinking clearly before implementation.

AI makes the old advice more important, not less:

Think twice, code once.

Before asking AI to build, define the problem.

Before accepting the answer, check the tradeoffs.

Before merging the change, verify the behaviour.

The value of engineering is shifting away from simply writing code and more toward shaping the right change.

What engineering with AI looks like

For me, engineering with AI means treating it less like a magic answer box and more like a collaborator that needs structure.

The work starts before implementation: write the requirement, narrow the scope, give useful context, ask for risks, and force a plan before code.

After implementation, the responsibility comes back to the engineer: review the diff, run the checks, and decide whether the change belongs in the system.

A useful AI-assisted loop can be simple:

Requirement → gaps → plan → small change → review → checks → notes

This is not the glamorous version of AI development.

But it is closer to real engineering.

Because real engineering is not just producing code.

It is producing reliable change.

The real shift

The next shift in software engineering will not be about who can generate the most code.

That advantage is already becoming cheaper.

The harder advantage is knowing what should be built, how it should fit into the system, and how to verify that it works.

That is where AI-assisted engineering becomes interesting.

Not because AI replaces engineering judgment.

Because it makes engineering judgment harder to skip.

Most major engineering tools became valuable only after teams changed the workflow around them. Git changed collaboration. Cloud changed infrastructure. CI/CD changed shipping.

AI is broader, messier, and moving faster than those shifts, so I do not want to pretend it will follow the exact same path.

But the lesson still feels familiar:

The tool matters.

The workflow around the tool matters more.

The engineers who benefit most will not necessarily be the ones who use AI the most. They will be the ones who design better loops around it: clearer specs, smaller changes, stronger reviews, better tests, and more deliberate decisions.

So yes, most engineers use AI now.

But only a few are starting to engineer with it.

The best engineers in this phase may not be the fastest prompt writers.

They may be the ones who can slow the problem down before speeding the implementation up.