Coding agents do not fail because they are lazy. They fail because we ask them to execute before the work has been made executable.

You have probably seen this happen. You give an agent a feature request that feels clear in your head. It reads the codebase, makes a few reasonable choices, writes a lot of code, and opens a pull request. At first glance, the work looks impressive. Then review starts...

The edge cases are not quite right. The implementation chose the wrong boundary. It requires a data migration that is just a little uncomfortable. The product semantics are slightly off. The tests prove the code runs, but not that it does the thing you meant. Now the human reviewer has to reconstruct the original intent, reverse-engineer the agent's assumptions, and decide whether the implementation is wrong or the prompt was incomplete.

This is the expensive part of agentic programming. Not generation. Review.

The wrong question is: How do I prompt the coding agent better?

The right question is: Has this feature been turned into an execution-ready artifact?

Feature Blueprinting is a reusable agent skill that turns an idea into a reviewed, phase-gated implementation package. It does not ask an agent to be more confident. It removes the decisions the agent should not be making during implementation.

§The Problem: Ambiguity Compounds During Implementation

Before coding agents, ambiguity was expensive but survivable. A strong engineer could take a vague feature, ask questions, explore the codebase, infer product intent, and make judgment calls while implementing. Some of those decisions happened in design. Some happened in Slack. Some happened silently in the engineer's head. That worked because the same person was usually carrying the context from ambiguity to implementation. Coding agents break that assumption.

Agents are good at extending visible patterns. They are good at following constraints. They are good at producing code when the shape of the work is already clear. But when the work contains unresolved product semantics, unclear ownership boundaries, or hidden architectural decisions, the agent still has to pick something. It will make a locally plausible choice based on the context it can see.

Sometimes that choice is right. Often, it is merely reasonable. Reasonable is dangerous, because it looks correct until review reveals that the agent solved a different problem than the one you intended. The problem is not that the agent failed to code. The problem is that the task still contained decisions that should never have been left to the implementation phase. The coding agent has no idea but to introduce entropy.

This loop is slow because review is doing two jobs at once: evaluating the code and discovering what the feature was supposed to mean.

§The Primitive: Execution Scaffolding

In an agent-native environment, scaffolding usually means generators, templates, agent skills, hooks, and rules. These mechanisms reduce repetitive decisions. They make the correct path easier to follow and the incorrect path harder to invent.

Feature Blueprinting is scaffolding too, but it operates one layer earlier.

Traditional scaffolding maps:

Feature Blueprinting maps:

It does not generate code directly. It generates the structured context that makes code generation reliable.

That distinction matters. Most teams try to improve agent output at the moment of execution. They write longer prompts, attach more files, or ask the model to be more careful. Sometimes that helps. But if the feature itself is still ambiguous, a better prompt just gives the agent more room to make confident guesses.

Feature Blueprinting moves the work upstream. It turns vague intent into reviewed artifacts before implementation begins.

§The Skill At A Glance

The skill is phase-gated. Each phase has an entry condition, an allowed set of actions, an artifact, and an approval gate. The gates matter as much as the artifacts. They prevent unresolved design issues from being smuggled into implementation scope.

The phases are:

1. Design doc readiness
2. Critical review
3. Outline locking
4. Stage-by-stage authoring
5. Ticket packaging

Each phase removes a different class of ambiguity.

The point is not documentation for documentation's sake. The point is to make sure that by the time a coding agent receives a task, the remaining work is actually implementation work.

§Phase 0: Design Doc Readiness

Phase 0 answers what should happen, not how to implement it.

This sounds obvious, but it is where many agent workflows go wrong. A feature idea often mixes product intent, implementation guesses, migration concerns, and open questions in the same paragraph. If you hand that to an agent, it has to separate those layers itself.

In Phase 0, the agent helps create or validate a design doc. It can ask product questions, read code to verify current behavior, query available evidence, and edit the design doc when there is a working document path. It cannot start implementation planning, draft tickets, or write code.

The output is one of three things:

• a design doc accepted as ready for critical review,
• a readiness report listing missing sections and blocker questions,
• or a numbered set of questions that must be answered before scoping.

The design doc should include product semantics, worked examples, decisions and rationale, composition rules, data model implications, trade-offs, open questions with named resolution phases, and explicit out-of-scope items.

The most important section is the decision table:

This forces non-obvious choices into the open. If a behavior could reasonably work two ways, the doc should say which one we chose and why. If a question is unresolved, it should not be hidden in prose. It should be named, assigned to a resolution phase, and kept out of implementation until answered.

The impact is simple: Phase 0 prevents the agent from inventing product semantics while writing code. It creates a semantic source of truth before technical scoping begins.

§Phase 1: Critical Review

Phase 1 reviews the design doc adversarially before technical scoping begins.

This is not a copy edit. The goal is to find contradictions, hidden migrations, edge cases, and places where the current codebase may fight the proposal. The reviewer reads the design doc, verifies claims against the actual code, and produces findings.

The important rule is that findings are not silently fixed.

The owner has to triage them:

• Accept the finding and update the design.
• Reject it and document why it is not a concern.
• Refine the proposal.

This matters because design review and implementation scoping are different activities. If a reviewer finds that the design contradicts the current data model, that is not a scoping detail. It is an upstream design issue. If you absorb it downstream, you end up with implementation plans that quietly compensate for unresolved product decisions.

The skill looks for composition rules that fail edge cases, storage semantics that contradict existing code, data migrations hidden behind "no schema changes," UI claims that imply backend complexity, decisions whose costs are stated without contrast, open questions without a named resolution phase, and deferred work that is actually required for correctness.

A finding is structured so the owner can act on it:

1. Finding title
   - Concern: <what may be wrong>
   - Evidence: <doc section and/or verified file reference>
   - Why it matters: <impact if unresolved>
   - Severity: <blocking/non-blocking>
   - Needs owner decision: <yes/no and question>

The impact is that Phase 1 moves adversarial review before technical planning. Agents can execute a resolved decision. They should not be responsible for discovering that the decision was never actually resolved.

§Phase 2: Outline Locking

Phase 2 locks the technical scoping outline before writing the full scope.

This is where the work becomes explicitly scoped. The output is not the full implementation plan yet. It is the shape of the plan: sections, depth, deviations, clarifying questions, out-of-scope items, and prep-work status.

The most useful concept here is depth calibration.

Not every surface of a feature needs the same level of detail. Backend might need implementation-ready detail. Frontend might only need interface-level boundaries. Analytics might be out of scope. Testing might need specific behavioral cases but not exact file paths.

Feature Blueprinting makes that explicit:

Depth is chosen independently for backend, frontend, data/modeling, infrastructure, analytics/audit, testing, and rollout. The skill does not assume backend should be deep or frontend should be shallow. The selected depth controls section shape and citation expectations.

This is one of the places where the methodology becomes very practical. Without depth calibration, scoping docs drift. Some sections become over-specified. Others stay vague. The agent receives uneven instructions and has to guess where precision matters.

Depth calibration tells the agent how much freedom it has on each surface.

The impact is that Phase 2 prevents two common failures: drafting a giant plan before the owner has agreed to the shape, and turning design gaps into implementation details.

§Phase 3: Stage-By-Stage Authoring

Phase 3 writes the scoping document one section at a time.

For each section, the workflow is:

1. Research the current code.
2. Verify every code reference by direct file read.
3. Draft only the approved section.
4. Pause with what was confirmed, what contradicted the outline, what decisions are needed, and what prep-work candidates surfaced.
5. Wait for the owner to continue, revise, escalate, or move to the next section.

This is slower than asking an agent to generate the whole plan in one pass. That is the point.

Large one-shot plans tend to sound coherent while hiding weak assumptions. Section-by-section scoping creates checkpoints where the owner can catch drift before it spreads.

The escalation rules are what make this phase reliable:

The scoping doc is not a fictional ideal of how the feature should work. It is grounded in the actual codebase, with citations and boundaries that an implementer can follow.

The impact is that Phase 3 keeps the artifacts honest. It prevents the agent from drifting across sections, inventing code references from search results, or hiding prep work inside the feature implementation.

§The Prep-Work Loop

Prep work is not a formal numbered phase, but it is one of the most important pressure valves in the skill.

The loop runs across the methodology. During design review, outline locking, section authoring, and late scoping discoveries, the agent keeps asking the same question:

Is there a standalone refactor or bug fix in the surrounding code that would shrink the feature PR and is independently shippable?

That last clause matters. Not every cleanup idea is prep work. A candidate only becomes prep work if it passes three gates:

1. It is independently valuable. The change is still correct if the feature never ships.
2. It measurably shrinks the feature PR. You can point to the feature scope and say what becomes simpler.
3. It is safe to ship alone. It does not require a coordinated feature release, a feature flag, or a risky one-way migration.

If any gate fails, the work stays somewhere else. It may remain inside the feature scope, get rejected, or move upstream because it exposed a design gap. This is the part that keeps the loop honest: prep work is not a junk drawer for everything nearby that could be nicer.

This matters because agents are very willing to mix preparatory changes with feature changes. That creates large PRs where the reviewer has to evaluate cleanup, architecture, behavior, and product semantics at the same time.

For example, suppose a feature needs to add a new composition rule, but the current resolver has duplicated validation branches that make every new rule touch three call paths. If consolidating that validation is useful on its own, clearly reduces the feature diff, and can ship without changing product behavior, it is prep work. Land it first. Then the feature scope can describe the new rule against the simpler resolver instead of asking one PR to do both the cleanup and the product change.

Candidates should be tracked explicitly. Early in Phase 2, a candidate might only be proposed. During Phase 3, code research may prove it should be accepted, rejected, promoted into the feature, or promoted back into the design doc because it changes the product semantics. Once at least one candidate is accepted, it gets its own pre-work scoping doc. That doc is detailed enough to become Linear tickets later, but it is still a working artifact until the feature scope is approved.

The loop also needs a freeze point. Prep enumeration should stop when Phase 3 is complete and the final checkpoints are no longer surfacing new candidates, or when the owner explicitly freezes prep scope. Otherwise the workflow can become an endless search for nice-to-have cleanup. New ideas after the freeze become follow-up work unless the owner deliberately re-opens prep scoping.

Prep-work splitting keeps the implementation path clean. It lets the team land risk-reducing work first, then hand the agent a feature scope that no longer depends on incidental refactors.

§Phase 4: Ticket Packaging

Phase 4 is optional. It packages approved working docs into Linear-ready ticket content after scoping is complete.

This is a small detail that changes the entire system.

In many teams, the ticket is the source of truth. A feature starts as a ticket, expands through comments, picks up clarifications in Slack, and eventually becomes whatever the implementer understood from the pile of context.

That does not scale well to coding agents.

Tickets are too small to hold the full design and too operational to preserve nuanced decisions. They are useful for routing work, tracking progress, and assigning execution. They are not where product semantics should live.

In Feature Blueprinting, tickets are wrappers around approved working docs. The ticket summarizes the task, links back to the source artifacts, and keeps execution moving. If the ticket conflicts with the docs, the docs win.

The source rules are explicit:

• Design semantics come from the design doc.
• Prep task scope comes from the pre-work scoping doc.
• Implementation order and technical implications come from the feature scoping doc.
• If the docs conflict, the workflow stops and asks which source should be corrected.

The impact is that Phase 4 gives agents an execution wrapper without weakening the working docs as the source of truth. The agent is not expected to infer the entire feature from a few paragraphs. It is pointed at the reviewed artifacts that define the work.

§The Artifact Stack

Feature Blueprinting works because each artifact has a job.

The design doc answers what the feature means.

The findings document what could be wrong.

The locked outline says which implementation surfaces matter and how much detail each one needs.

The prep-work doc separates enabling work from feature work.

The feature scoping doc turns the locked design into implementation guidance.

The tickets route execution without becoming the source of truth.

This stack matters because agents need more than context. They need context with authority. They need to know what is locked, what is open, what is out of scope, and what evidence supports the plan.

§Why This Works

Feature Blueprinting works because it reduces decision surface area before implementation.

Every feature contains multiple kinds of decisions:

• Product decisions: what should happen?
• Semantic decisions: what does this state or action mean?
• Architectural decisions: where should the behavior live?
• Data decisions: what must be stored, migrated, or preserved?
• Interface decisions: which components, services, routes, or APIs are involved?
• Testing decisions: what proves this is correct?
• Rollout decisions: what needs to happen before this is safe?

If those decisions are not made before implementation, the implementer makes them during implementation.

For a senior engineer, that can be fine. For an agent, it is risky. Not because the agent is incapable, but because it cannot reliably know which decisions are flexible and which are load-bearing.

Feature Blueprinting labels the load-bearing decisions.

It tells the agent what is locked, what is out of scope, what current code matters, what prep work should happen first, and how much detail each surface requires. The agent can still make local implementation choices, but the shape of the work is constrained.

That is exactly what good scaffolding does.

§The Review Shift

The goal is not to eliminate review.

The goal is to move the right review earlier.

Late review of agent-written code is expensive because the reviewer has to evaluate two things at once:

1. Is the implementation technically correct?
2. Did the agent choose the right interpretation of the feature?

Those should not be coupled.

Feature Blueprinting separates them. Humans review product semantics, scope, trade-offs, and execution boundaries before code exists. Agents then implement against that reviewed context. Code review still happens, but it becomes more focused. The reviewer can ask whether the implementation matches the blueprint instead of rediscovering the blueprint from the implementation.

That is a much healthier loop.

§How To Know A Feature Is Ready For An Agent

A feature is ready for an agent when the remaining work is implementation, not interpretation.

You should be able to answer:

• What product behavior is locked?
• Which decisions were considered and rejected?
• Which open questions remain, and which phase resolves them?
• Which implementation surfaces are in scope?
• How deep should each surface be scoped?
• Which current code paths were verified?
• Which prep tasks should land before the feature?
• What tests or verification targets prove the work is correct?
• Where are the source docs if a ticket is incomplete?

If those answers live only in someone's head, the feature is not ready.

If those answers live across Slack, tickets, comments, and guesses, the feature is not ready.

If those answers live in reviewed artifacts with explicit approval gates, the agent has a real execution environment.

§The Agent-Native Connection

In an agent-native environment, agent reliability is shaped by the environment more than by the model alone. Codebase structure, scaffolding, validation systems, and intent representation determine whether agents can produce useful work consistently.

Feature Blueprinting sits between scaffolding and intent.

It is scaffolding because it is a repeatable mechanism that turns feature ideas into structured artifacts. It is intent representation because those artifacts describe what the system should do, why decisions were made, and where implementation should happen.

The reusable workflow belongs to scaffolding.

The documents it produces belong to intent.

Together, they make agents more reliable because they convert implicit human judgment into explicit execution constraints.

This is the broader lesson: agents do not only need better context. They need better-shaped context.

A giant pile of notes is not an execution environment. A precise design doc, reviewed findings, calibrated scope, prep-work split, and ticket wrapper is.

§Download The Skill

The Feature Blueprinting skill is designed to be dropped into an agent environment and run as a phase-gated workflow.

When the downloadable version is available, this post will link directly to it here.

§The Right Question

When agent work goes poorly, it is tempting to blame the model, the prompt, or the lack of context.

Sometimes that is correct. But often the real issue is that the task was never made executable.

The wrong question is:

Can the agent build this from my prompt?

The right question is:

Have I removed every decision that should not be made during implementation?

Feature Blueprinting is the process of answering that question before code exists.

It front-loads human judgment where human judgment is most valuable: product meaning, trade-offs, architectural boundaries, and execution shape. Then it gives coding agents what they are best at: a constrained, well-scoped implementation problem with clear validation targets.

That is how agentic engineering scales.

Not by asking machines to guess better.

By designing the work so they do not have to guess.