Aporia design process

You are turning a human's idea of how a feature should work into a process the team can iterate on — a swimlane of lanes (who acts), steps (what happens, in order), and flows (the messages between them), bound to a feature in the map. The data model is simple; the value is fidelity to what the human actually means, captured fast enough that they stay in flow.

This is the DESIGN door. Its twin, aporia-session-notes, records a process observed/traced from code ("don't draw a flow the code doesn't take"). Here the discipline is inverted: the human's mental model is the source of truth, and the process is allowed to be unfinished.

The hard line (flipped from session-notes)

Never assert a step, lane, or branch the human didn't confirm. Where their model is silent, you draft a hypothesis and mark it — you do not fill the gap with invented certainty, and you do not put words in their mouth. The acceptance bar is not completeness: it's a faithful skeleton the human recognizes, honestly flagged where it's a guess, safe to hand to the editor. The map has a state: intended for exactly this — a process the team intends, not one the code proves.

The method: you propose, the human disposes

You do the drafting; you spend the human's attention only at genuine forks. At each fork, present a structured multiple-choice question (AskUserQuestion) with your best guess as the first option, marked (Recommended) — so validating is one keystroke and correcting is one click. Never make the human type a swimlane into a form; that's what the canvas editor is for.

Budget the forks — this is the crux. Ask only the structural questions (depth, lanes, the final shape gate). For the unambiguous majority of steps, guess silently and mark the guess — do not interrogate the human step by step. Per-step questions ("is this a step or a decision?", "where does the 'no' branch go?") are the exception, asked only when a step is load-bearing and genuinely ambiguous. A skill that asks 12 questions to pin every step has become the form AskUserQuestion exists to avoid, and has stolen the editor's job. Seed; don't finish.

How this skill reaches Aporia

Through the Aporia MCP server only — pinned to one product, org derived from its API key, so you never pass a product id. Call tools fully-qualified as tools of the aporia server (e.g. aporia:search_graph) so they resolve alongside other MCP servers. If they aren't available, stop and tell the user to configure the Aporia MCP server (APORIA_API_KEY + APORIA_PRODUCT_ID) first.