Interaction Map — Design the Flow Before the Code
You are designing an interaction, not documenting one. Nothing has been built yet, and that is the entire advantage: every state can be decided instead of discovered, and the contract between the two sides can be fixed before either side exists to drift from it.
This matters because of where features actually break. Not in the backend, not in the frontend, but at the seam — a button bound to nothing, a handler returning snake_case to a component reading camelCase, an error path nobody designed, a job dispatched to no worker. Every one of those is cheap here and expensive later. A state you forget to design now becomes a blank screen in production; a field name you leave vague now becomes an afternoon of debugging undefined.
So the output of this skill is an artifact, not a conversation: three complete lists, written to a file, that someone can build from without guessing and audit against afterwards.
SECURITY: Never write credentials, API keys, tokens, connection strings or secret values into the spec artifact. Name the mechanism ("authenticated via the existing session guard"), never the value.
Standalone by Design
This skill carries everything it needs. It does not call, summon, require, or degrade without any other skill. The mapping structure, the state taxonomy, the contract discipline and the completeness gate are all defined in this file. It runs identically in any agent, in any repo.
The artifact it writes is a plain file on disk. Anything that later reads that file — a person, a verifier, a test generator — does so on its own; this skill does not hand off to, wait on, or depend on any of them.
When to Use (Auto-Trigger)
Load this skill automatically. Do not wait to be asked. Run it when ANY of these occur:
- A new feature is being designed or requested and it has both a user-facing surface and a server leg.
- The user says "build", "add", "create", "we need" about a flow that does not exist yet.
- A feature's requirements are settled but nobody has described how it actually moves — what the user touches, what the server does, what comes back.
- A screen is about to be built that displays or submits server data.
- An endpoint is about to be written that a client will consume.
- A flow is being significantly reshaped, so the existing design no longer describes it.
How to auto-trigger:
- Announce: "Designing the interaction map for
<feature>before any code — three lists, then the completeness gate." - Walk Phase 0 → 5 in order.
- Write the artifact. No artifact = not done.
- Apply the Completeness Gate. Below 1.0, the feature is not ready to build, and say so plainly.
When This Is The Wrong Skill
If the flow already exists in code, stop. Reconstructing a map from code you are about to audit is a different job with different rules — there, the code is evidence and the map is a finding. Here, there is no code and the map is a decision. Say which situation you are in before proceeding.
A useful test: can you point at the handler? If yes, this is not a design task. Design what does not exist; audit what does.
Golden Rules
- Decide, do not defer. The value of designing before building is that every state gets chosen deliberately. "We'll figure out the error case later" is the failure this skill exists to prevent — later is production.
- Specify the seam first, then both sides. The exact field names, types and status codes are fixed once, in one place, before either the client or the server is written. Two independently-written shapes always drift.
- Never invent a requirement. If the intent is genuinely unknown, write it as an open question with who must decide it. A guessed requirement is worse than a blank, because it gets built.
- Every step gets every state. Idle, loading, success, empty, error, forbidden. A state that genuinely does not apply is marked
NOT APPLICABLEwith a reason — never simply absent. - Exhaustive beats elegant. This artifact is read by someone building from it. A missing row is a bug they will ship. Completeness is the only quality that matters here.
- No prose where a list belongs. "The user logs in and sees their dashboard" is a summary. A numbered step with a screen, an element, a trigger and a next-step is a specification.
- 1.0 or it is not ready to build. See the Completeness Gate. The counts are countable; rounding up is banned.
Reasoning Discipline
Forbidden and Required Phrases
Never write into the artifact:
- "etc.", "and so on", "and the usual fields", "similar to the above"
- "TBD", "TODO", "we'll decide later", "as appropriate"
- "returns the user object" (which fields?), "handles errors" (which errors, how?)
- "standard CRUD" (write the four operations out)
Always write:
- Every field by name, with its type
- Every status code the endpoint can emit, each with the client's branch for it
- Every state, or an explicit
NOT APPLICABLE — <reason> - Open questions as
OPEN: <question> — decided by <who>
The Placeholder Trap
Designing is where placeholders feel harmless and are most damaging. "The response includes the usual user fields" reads as complete and specifies nothing; whoever builds from it invents the fields, and whoever builds the other side invents different ones. That is the drift this artifact exists to prevent, introduced by the artifact itself.
Every abbreviation you are tempted to write is a decision you are pushing onto someone with less context than you have right now.
Design the Ugly Paths First
The happy path is the one everyone designs and the one that usually works. Loading, empty, error and forbidden are where features fail, and they are also the cheapest to specify before code exists. When you find yourself designing the success case in detail and the failure case in a sentence, you have the effort backwards.
Phase 0 — Scope
Pin the boundary before designing inside it.
FEATURE: the one feature being designed, named precisely
ACTORS: who performs it (guest, user, admin, system, webhook, cron) —
each one is walked through the whole flow later
ENTRY POINTS: where the flow can begin (URL, screen, button, API call, event, schedule)
EXIT POINTS: where it legitimately ends (persisted record, rendered state, sent
notification, dispatched job, redirect)
OUT OF SCOPE: adjacent things this design does NOT cover, stated explicitly
CONSTRAINTS: what the design must respect — existing schema, existing endpoints,
framework conventions, an established design system, performance limits
On constraints. Read the codebase before designing into it. An interaction designed against conventions the project does not use produces a spec nobody can build cleanly. Name the patterns you are following.
Exit condition: All six fields filled and stated back.
Phase 1 — Map A: The User Interaction Flow
Every step the user takes, every state they can land in. Numbered.
A<n>. STEP: what the user does or sees
SCREEN: the route or page it happens on
ELEMENT: the exact control (button, link, input, toggle, drag target)
TRIGGER: the event that fires (click, submit, change, route enter)
PRECONDITION: what must be true to reach here (auth, role, prior state, flag)
NEXT: which A-step or exit point follows
STATES: all six, each decided — see below
The Six States — decided, never discovered
For every step, specify each of these or mark it NOT APPLICABLE with a reason:
IDLE — what renders before the user acts
LOADING — what renders while waiting; is the trigger disabled; is there a skeleton,
a spinner, an optimistic update
SUCCESS — what visibly changes when it works; what the user is told
EMPTY — what renders when there is legitimately no data; what the user can do
from there (an empty state with no next action is a dead end)
ERROR — what renders per failure kind; the message text; whether the user can
retry, and what the retry does
FORBIDDEN — what an actor without permission sees: hidden, disabled with a reason,
or a redirect. Pick one and say which.
An unspecified state is not a small omission. It is the single most common reason a finished feature renders a blank screen.
Exit condition: Every step numbered, every step carrying all six states, every step with a NEXT or a declared exit.
Phase 2 — Map B: The Server Flow
Every hop the request takes. Numbered.
B<n>. HOP: what this layer does
IN: what it receives (shape, types)
OUT: what it produces (shape, types)
SIDE EFFECT: writes, events, dispatches, external calls, cache changes
FAILURE: how it can fail, and exactly what it emits when it does
Design the full chain. Omit no layer that this stack has:
entry (route / endpoint / subscriber / schedule / webhook)
-> middleware (auth, tenancy, throttle, CSRF, CORS)
-> authorization (policy, gate, guard, role check)
-> validation (rules, schema, DTO) — and the exact message per failed rule
-> controller / handler
-> service / action / use-case
-> model / repository
-> database (tables and columns touched; new columns flagged as migrations)
-> side effects (events, listeners, jobs, queues, notifications, mail, webhooks)
-> response (serializer, status code, body shape)
Async legs are designed, not assumed. A dispatched job needs its own B-hops: what consumes it, on which queue, what happens when it fails, whether the user is told. A design that ends at "dispatch the job" has designed half a feature.
Validation is designed on both sides at once. Write each rule once here, and note that the client shows it and the server enforces it. Rules invented separately on each side are the classic mismatch — the user gets rejected by a rule the form never mentioned.
Exit condition: Every hop numbered with IN, OUT, side effects and failure behavior. New schema flagged.
Phase 3 — Map C: The Seam Contract
This is the phase that earns the skill. The contract is written once, here, before either side is built — so there is nothing for the two sides to drift from.
One row per client↔server interaction:
C<n>. USER ACTION: which A-step triggers it
REQUEST: method + path
REQUEST BODY: every field by name, with its type, and whether required
AUTH: what proves the caller may do this
SUCCESS: status code + every response field by name, with its type
ERRORS: every status this can return, each with its body shape
AND the A-step state the client moves to for it
RESULTING STATE: which A-step or state the UI moves to on success
Rules for writing the contract
- Name every field and give it a type.
user.first_name: string— not "the user's name". The name in this table is the name both sides will use; that is the entire point of writing it here. - Pick one casing convention and state it. The mismatch between
first_nameandfirstNameis the single most common seam bug in existence, and it is free to prevent at this moment. - Write the envelope, not just the payload. If the response is
{ data: [...], meta: { total } }, write that. A client built for a bare array against a server that paginates is a guaranteed break. - Every error status gets a client branch. A status the server can emit with no designed client response is a blank screen waiting to happen.
- Nullability is part of the type.
avatar_url: string | nulltells the builder to handle the null.avatar_url: stringtells them not to, and they won't. - Dates and money need a format. ISO 8601, a timestamp, minor units, a precision. "A date" is not a type.
Prefer one source of truth over a written contract
If this stack can make the contract unbreakable rather than merely written — shared types across both sides, a schema both ends derive from, generated clients — say so here and design it that way. A contract a type system enforces cannot drift; a contract in a document can. Note which mechanism this feature will use, and if the answer is "none, both sides hand-written", record that as a known risk in the artifact.
Exit condition: Every interaction has a row; every row has full request and response shapes with types; every error status has a branch.
Phase 4 — Walk Every Actor
For each actor from Phase 0, walk the whole flow start to finish and write what they experience. Not a summary — the actual path.
ACTOR: <name>
Reaches: which A-steps
Blocked at: which A-steps, and what they see there (the FORBIDDEN state)
Sees: which fields, and which are withheld
Can perform: which C-links
This is where permission design actually gets done. A flow designed only for the happy actor ships either a leak (someone sees what they should not) or a dead end (someone is blocked with no explanation). Both are cheap to prevent here.
Exit condition: One walk per actor, with reached and blocked steps named.
Phase 5 — The Completeness Gate
This gate is countable. Do the arithmetic, then apply it.
COUNTS
A-steps: N
A-steps with all 6 states: N <- must equal A-steps
A-steps with NEXT or exit: N <- must equal A-steps
B-hops: N
B-hops with IN/OUT/failure: N <- must equal B-hops
C-links: N
C-links with full shapes: N <- must equal C-links
C-links with every error
status branched: N <- must equal C-links
Actors: N
Actors walked: N <- must equal Actors
Placeholders in artifact: N <- must be 0
Open questions: N <- each with a named decider
-
1.0— every count matches its target, zero placeholders, and every open question has a named decider. READY TO BUILD. The only clean pass. -
0.95 – 0.99— CONDITIONAL. Permitted only when every gap is named: which steps, hops, links or actors are incomplete, and what is missing from each. A conditional design may not be described as ready, complete, or finished, and may not be summarized in a way that hides the gaps. State the number and the gap list together or not at all. -
< 0.95— NOT READY. Report what is missing. You may not describe the design as done under any wording, and building from it is a stated risk.
The score is computed, not chosen. It comes from the counts above. Never round up: a design with nine of ten steps fully stated is 0.9, not 1.0, and 0.94 is not 0.95.
Any of these caps the score below 1.0 regardless of the counts: a state left unspecified and unmarked; a response field without a type; an error status with no client branch; an actor not walked; the word "etc." anywhere in the artifact; an open question with no named decider.
The Leniency Check
Before writing the number, answer these in the artifact:
1. THE ARITHMETIC Does every count equal its target? If not, the score is
the ratio, not a judgment.
2. WHAT I DECIDED Which states or shapes did I choose myself rather than being
told? List them — the user may disagree, and now is when
that is cheap.
3. WHAT I ASSUMED Every assumption about intent, stated. MANDATORY even at 1.0.
4. THE HONEST ONE What would the person building this have to come back and
ask me? Name it specifically. "Nothing" is not acceptable —
if you cannot name one, say which part of the design is
thinnest and why.
Phase 6 — Write the Artifact
Write the design to a file. A map that lives only in a conversation is lost the moment the session ends, and the people who need it most are the ones who were not here.
Path: docs/flows/<feature>-flow.md unless the project has an established location for design docs — follow the project's convention if one exists, and say which you used.
Structure the file exactly as the phases ran: scope, Map A, Map B, Map C, actor walks, the counts, the leniency check, open questions. A reader should be able to build from Map A and Map C alone, and check their work against the counts.
State the path back to the user when done.
Banned (any one = the design does not pass)
- Writing "etc.", "and so on", "the usual fields", or "similar to above" anywhere in the artifact.
- Leaving a state unspecified without marking it
NOT APPLICABLEand why. - A response field with no type, or a "type" that is not one (
a date,the user). - An error status with no designed client branch.
- Designing the happy path in detail and the failure paths in a sentence.
- Inventing a requirement instead of recording an open question with a decider.
- Skipping an actor walk because the permissions "are obvious".
- Ending an async leg at "dispatch the job" without designing what consumes it.
- Finishing without writing the artifact to a file.
- Reporting CONDITIONAL as ready, or describing anything under 1.0 as complete.
- Rounding the count up.
Handoff
This skill is self-contained. When the design is done, the natural next steps — none of which this skill invokes, waits on, or requires:
| Next | When |
|---|---|
| Build from the artifact | Gate is 1.0 |
| Close the gaps, re-run the gate | Gate is conditional |
| Get the open questions decided | Any question has a named decider and no answer |
| Verify the built flow against this artifact | After the code exists |
Decide every state. Fix the contract once. Write it down. Ready only at 1.0.