The 16 laws that grade agentic AI surfaces and specs

The spec names who is stuck, what they cannot do today, and what observably changes for them when the work ships. A solution restated as a need ('we need a dashboard') is not a problem statement; the outcome must be expressible without naming the chosen mechanism.

Most wasted engineering traces to solving a well-built wrong thing. Working-backwards practice and jobs-to-be-done research converge on the same discipline: a spec that opens with the user's blocked outcome lets every downstream decision be tested against it, while a spec that opens with a mechanism forecloses alternatives before the first review.

• Open the proposal with the affected user/actor and the blocked outcome, in their language, before any solution vocabulary.
• State how the world is observably different after shipping — what the actor can do, stop doing, or stop working around.
• If the problem statement already names the implementation, rewrite it until the mechanism could be swapped without changing the problem.
• Include the evidence the problem is real (support signal, telemetry, direct report) or mark it explicitly as a hypothesis.

The spec covers one coherent change with an explicit boundary: what is in scope, what is deliberately out of scope, and which existing capabilities it touches. Anything the change does NOT do is stated, not implied.

Batch size is the strongest lever on delivery risk: small, bounded changes fail visibly and recover cheaply, while unbounded specs accumulate silent scope until no single review can hold them. An explicit out-of-scope list is also the cheapest defence against scope creep, because exclusions become decisions on record rather than omissions open to relitigating.

• Carry an explicit out-of-scope section; every reviewer-tempting adjacency is either pulled in deliberately or excluded on record.
• Name the existing capabilities/modules the change touches; a delta that touches unnamed capabilities is a scope breach.
• If the work cannot be described as one coherent change, split the spec before building, not during.
• Prefer follow-up specs over grow-in-place: the boundary of THIS change stays fixed once approved.

Every requirement carries an observable acceptance signal: a scenario, measurement, or binary check a reviewer could run without asking the author what was meant. 'Works well', 'fast', and 'intuitive' are not acceptance criteria until they are bound to an observable.

Unclear success criteria are the leading stall cause in real-world initiatives and the core of the specification-ambiguity bucket, the largest failure class in the MAST taxonomy (~42% of traced failures). A requirement without an acceptance signal defers its real definition to the implementer's guess and the reviewer's mood — the two most expensive places to discover disagreement.

• Bind each requirement to at least one scenario (given/when/then), threshold, or observable behaviour.
• Write acceptance signals a NON-author can execute: no hidden context, no 'as discussed'.
• Quantify quality words or delete them: name the metric and the bar, or restate the requirement behaviourally.
• The definition of done for the whole change is the union of its acceptance signals — nothing more, nothing less.

Material design decisions name the alternatives considered and why they were rejected; open questions are listed with a named owner and a resolution point. A decision without its rejected alternatives is an assertion, not a decision.

Architecture-decision-record practice exists because unrecorded decisions get relitigated at the most expensive moment — mid-build or in review — and because the rejected alternative is where the reasoning lives. Recording it converts future 'why didn't we just…' threads into a one-line pointer, and it exposes weak decisions to challenge while changing course is still cheap.

• For each material decision, record at least one considered alternative and the concrete reason it lost.
• Keep an open-questions list where every entry has an owner and the milestone by which it must resolve.
• Distinguish decisions (closed, with trail) from assumptions (open, with a validation plan).
• When a decision is imposed from outside (compliance, platform, founder call), say so — the trail is the constraint's name.

Each downstream role can start without asking: interfaces, data contracts, states, and edge behaviour are stated where the engineer needs them, and flows, states, and content intent are stated where the designer needs them. The spec is the contract between roles, not a memo from one.

Inter-agent (and inter-human) misalignment is the second dominant failure bucket in the MAST taxonomy (~37%, Cemri et al. 2025): work built to different unstated contracts integrates late and fails at the seam. Every question a downstream role must ask the author is a defect in the spec — and in an agentic workflow, an unanswerable question becomes a silent guess instead.

• State interfaces and data contracts (shapes, states, error cases) at the level the implementing role consumes them.
• Describe user-facing states completely: empty, loading, error, success, and permission-denied are part of the contract.
• Write for the reader who was not in the meeting; the spec carries its own context.
• If a downstream role would need to ask a question to start, answer it in the spec or list it as an owned open question.

Where the built thing will be agentic or user-facing, the spec cites the governing principles and laws it must satisfy — delegation visibility, approval gates, familiarity floors — as requirements, not as review findings waiting to happen. Governance applied at the spec is a design input; applied after the build it is rework.

Every doctrine violation caught at review costs a rebuild; the same violation named in the spec costs a sentence. Shifting the doctrine left is the whole premise of governing the entry point: the architect and design validators exist to catch drift, but a spec that never encoded the doctrine gives them drift to catch on every run.

• Name the specific agentic principles the built system must satisfy (e.g. background-work visibility, explicit approval gates) as requirements with acceptance signals.
• Name the experience-design laws the surface must satisfy (e.g. familiarity, accessibility floor) where a surface is being built.
• Plan the validation: the spec says which validators will score the result and what score gates ship.
• Where the doctrine is deliberately not applied, record it in the decision trail with the reason.

Tasks map to requirements and requirements map to tasks: no orphan tasks that serve no stated requirement, no requirement with no task that implements it. The task list is the requirements restated as work, not a second, parallel plan.

Traceability is how a spec stays honest through the build: an orphan task is scope creep with a checkbox, and an unimplemented requirement is a silent cut nobody decided. When tasks and requirements drift apart, the spec stops governing the work and becomes documentation of an intention.

• Every task names the requirement(s) it serves; every requirement is reachable from at least one task.
• Cutting a task mid-build means revisiting its requirement on record — a decision, not an accident.
• Order tasks by dependency so the build path is derivable from the spec.
• Verification tasks (tests, validator runs) trace to acceptance signals the same way build tasks trace to requirements.

The spec states what could fail, what is reversible and how (rollback, migration down-path, feature flag), and flags every irreversible or externally visible step for an explicit human gate. One-way doors are named as one-way doors before anyone walks through them.

The cost of a mistake is set by its reversibility, not its size: two-way-door decisions deserve speed, one-way doors deserve a named gate. Specs that never distinguish the two either gate everything (and stall) or gate nothing (and ship irreversible mistakes at the speed of the pipeline). In agentic execution this law is load-bearing: an agent will walk through any door the spec leaves unmarked.

• List the material failure modes and what the user/system experiences in each.
• State the rollback or down-migration path for every state-changing step; 'redeploy the old version' counts only if it is actually true.
• Flag irreversible steps (data deletion, external comms, publishing, payments) for an explicit human approval gate in the task flow.
• Prefer reversible mechanisms (flags, staged rollout, additive migration) and record when an irreversible one is chosen anyway.

Users spend most of their time in other products and arrive with a fully formed model of how navigation, search, forms, settings, and primary actions behave. Meet that model on arrival; novelty is permitted only where it demonstrably improves the outcome and is taught with lightweight cues.

Baymard's usability work shows familiar patterns reduce user errors ~30% and lift task completion ~18%. In agentic products the law tightens: when the underlying system is unfamiliar (an agent, not a tool), the surface must compensate by being maximally familiar — a novel agent behind a novel UI is two unfamiliar things stacked, and adoption collapses.

Decision time grows logarithmically with the number of equally-weighted choices. The remedy is not to remove capability but to stage it: surface fewer options at the moment of decision, then progressively disclose the rest.

The law is not linear — going from two choices to four costs proportionally more than twenty to twenty-two. Marking one plan 'most popular' collapses the effective option set. Experts pattern-match past it, but every new user faces it freshly on every screen.

The time to reach a target is a function of its size and distance from the current pointer. Big targets close to the resting position are fast and accurate; small distant targets create friction and error, across every input modality. Intentional friction (smaller, further, confirmation-gated) is the legitimate inverse for destructive actions.

WCAG 2.2 SC 2.5.8 (Target Size Minimum, AA) requires at least 24×24 CSS px; the European Accessibility Act (in force June 2025) makes this a compliance obligation. Apple HIG specifies 44×44 pt, Material 48dp, Fluent ~40px. Treat 44×44 CSS px as the working minimum for primary actions and 24×24 as the absolute floor with adequate spacing.

Working memory holds roughly four unrehearsed chunks; a chunk's size depends on the user's existing knowledge. Designers cannot expand capacity — only make content easier to chunk.

Miller's seven-plus-or-minus-two has been refined toward ~four chunks; 2026 neural modelling of prefrontal/basal-ganglia chunking supports treating capacity as adaptive. Familiar groupings (an acronym, a date format) count as one chunk; arbitrary items count as many.

People judge attractive interfaces as more usable, trustworthy, and valuable — often regardless of functional quality. Polish lowers cognitive friction, raises tolerance for minor flaws, and biases users toward staying long enough to find the value. It is forgiveness for minor friction, not for catastrophic friction.

Documented by Kurosu & Kashimura (Hitachi, 1995) and replicated since. In 2026 the effect is sharper for AI products: users have lower a-priori trust in agentic systems, and visual polish is one of the few first-contact signals that govern whether they extend the trust needed to delegate. It cuts both ways — beauty can mask real usability defects in testing (a research-integrity hazard).

People remember an experience by its emotional peak and its ending, judging the whole by the average of those two. Effort on average moments is largely invisible in memory; effort on the peak and the ending is disproportionately rewarded. A failure peak is at least as memorable as a success peak.

Kahneman's finding. The peak can be the moment of first value or completing a task the user expected to struggle with; the ending is whatever the user sees last (confirmation, success state, receipt). In agent interactions the completed-result moment is the most memorable, and the handover back to the user governs whether they delegate again.

Every product carries irreducible complexity that can only be relocated, never eliminated. The question is who absorbs it — the system, the developer, or the user. The right answer is usually a simple default with disclosed advanced controls, not the elimination of advanced controls.

Tesler's framing (Xerox PARC, 1980s): engineers should spend the extra week so millions of users don't each pay the cost. In 2026 this is the deep grammar of AI products — agents are valuable because they absorb complexity (Calendly is Tesler's Law as a product category). Over-simplification into hidden, un-inspectable defaults is the opposite failure mode.

A mental model is the user's internal story of how the product works — what it can do, what is happening now, what happens next. The gap between the model the user holds and the model the system implements is the single largest predictor of friction. The fix is to shape the surface to the model the user already brings and, where the system cannot match, to teach the delta explicitly with concrete demonstrations.

In 2026 this is the most consequential law for AI products and the most violated: users have a model for tools (deterministic) and assistants (conversational) but no shared model for agents (autonomous, stateful, non-repeatable). Lecturing the user into the system's model fails; aligning the surface and naming deviations works.