Experience Preflight

Decide what experience deserves to exist. Do not make people operate the seams between unfinished systems.

Start with the person and the work

Establish:

1. who is trying to do something;
2. what they believe they are doing;
3. the result they came for;
4. the real entry point;
5. the current path from entry to result;
6. every ending, including interruption, partial success, failure, and return.

Inspect the working interface, code, states, copy, and failure behavior when available. Separate what exists from what is proposed. Do not invent a smooth journey because isolated components pass tests.

Ask throughout:

> Why would anyone tolerate this, and have we mistaken machinery for an experience?

Count the hoops

Walk the recommended path and count:

• screens, clicks, fields, choices, and confirmations;
• accounts, logins, permissions, and consent steps;
• copied identifiers, codes, tokens, files, and commands;
• repeated information and facts the software can derive;
• browser, terminal, desktop, mobile, and provider context switches;
• decisions made before their consequences are understandable;
• waits without truthful progress or a recovery path;
• steps that configure machinery instead of producing the result.

The count is not a score. It forces every step to earn its place. Ask whether five steps can become one or two.

Remove machinery masquerading as an interface

Reject interfaces that merely expose database fields, environment variables, infrastructure objects, internal states, or tool arguments. Group input around intent. Derive, default, combine, delay, or remove everything the software already knows.

Do not make a person carry information between systems when software can transfer it safely. Never ask twice for the same fact unless a real security boundary requires confirmation.

Give one recommended path with strong defaults. Keep choices that express real intent; hide choices created only by implementation uncertainty. Put expert controls behind an advanced path and explain consequences without making people design the system.

Eliminate dead ends

Every state needs one clear continuation, one honest recovery path, or an intentional place to stop. Reject:

• blank states with no useful action;
• errors that say only “try again”;
• links that return to the same unresolved state;
• disabled actions with no explanation;
• success screens that leave required work unexplained;
• expired flows that discard progress;
• failures that force someone to guess which app or screen to visit next.

Resume when possible. Do not restart merely because the implementation lost the thread. For every interruption, say what survived, what may have happened, and what can safely happen next.

Measure completion at the result

Setup, authentication, deployment, a saved record, or an HTTP success code is not completion if the person still cannot do what they came to do.

Define the first moment the work becomes useful. Delay optional providers, integrations, preferences, and optimization until after that moment. A technical layer is enabling work, not a finished delivery.

Design people and agents as collaborators

When people and agents shape the same work, require:

• one canonical object rather than hidden parallel copies;
• the same underlying capabilities and consequences, even when the interfaces differ;
• enough live context to understand the object, selection, constraints, and recent changes;
• visible and attributable agent actions;
• interruption, undo, recovery, and resumption;
• an explicit rule for concurrent or conflicting intent;
• honest withdrawal of actions that are unavailable.

Do not reduce the agent to suggestions a person must re-enter. Do not give the agent an invisible privileged path that people cannot inspect, interrupt, or undo.

Put intelligence in the right place

Use the agent for intent, ambiguity, prioritization, interpretation, routing, and consequential tradeoffs. Use deterministic software for parsing, counting, validation, conversion, transformation, retrieval, storage, authorization, atomic mutation, and receipts.

A converter converts. A counter counts. A wake command wakes the selected worker. The agent may decide what the person meant or which target fits; the tool performs that decision predictably.

Reject magical tools described as “handle this,” “figure it out,” or “do the intelligent thing” when they hide a model decision. Make the model step visible and give it the context to judge.

Prefer a few clear command families over a catalog of overlapping tools. Combine operations when they share authority, safety, execution location, lifecycle, state ownership, and error behavior. Keep them separate when those boundaries differ.

Every tool must reveal before use:

• what it does and does not do;
• inputs, defaults, allowed values, and relevant current state;
• authority, likely effects, reversibility, and retry behavior.

After use it must return:

• the result or changed resource;
• whether an effect occurred or may have occurred;
• a stable, actionable error when it failed;
• a receipt or continuation when needed;
• the next safe action.

Never turn a possible external effect into an ambiguous “failed; try again.”

Expose limits and information loss

Challenge every maximum, timeout, page count, batch size, payload cap, retry count, and retention window. Name its authority: provider, protocol, format, measured resource boundary, security control, or chosen policy. A round number invented during implementation is not evidence.

Before large or variable work, expose the measurable scope and supported options. Let the agent or person choose whether to process all, select, stream, chunk, sample, reduce fidelity, or stop.

When work is partial, sampled, filtered, transformed, or lossy, say:

• the total scope when known;
• what was processed and omitted;
• whether the result is complete, estimated, a lower bound, or unknown;
• who chose the boundary and why;
• how to continue or choose differently.

Do not silently truncate or mistake a caller's current context, latency, cost, or memory budget for a universal limit.

Preserve safety without ceremony

For every permission or confirmation, name the threat it addresses. Prefer scoped authority, secure handoff, previews, reversible effects, receipts, and reauthentication at the consequential boundary. Remove ritual that does not change risk.

Write the replacement journey

Do not stop at criticism. Write the shortest complete path in the person's language:

1. entry point;
2. minimum input;
3. work performed by software and agents;
4. decisions that genuinely belong to the person;
5. truthful progress and interruption behavior;
6. successful, partial, and failed results;
7. retry, resume, undo, recovery, or safe exit;
8. the next useful action.

Delete every step that can be derived, automated, combined, or delayed. Preserve the reason the work exists.

Return the preflight

Lead with one verdict:

• Good experience
• Salvageable
• Machinery masquerading as an experience

Then include only what helps:

1. Promised result — person, intent, entry point, and useful ending.
2. Current journey — grounded in observed behavior, with unknowns named.
3. Hoops and dead ends — steps, repeated input, context switches, waits, ambiguity, and missing recovery.
4. Things to delete or combine.
5. Replacement journey — the shortest complete path.
6. People–agent collaboration — shared work, context, attribution, interruption, and undo when applicable.
7. Agent–tool boundary — judgment versus exact execution, catalog changes, effects, errors, and retries when applicable.
8. Limits and loss — authority for ceilings, completeness, omitted material, and continuation when applicable.
9. Unresolved decisions — only choices that genuinely change the experience.

Lead with the experience. Name implementation details only when they explain a visible problem or constrain the replacement.