Experience blueprint
An architecture diagram shows components. It does not show who is accountable
when one of them is wrong at 2am. The experience blueprint fixes that by naming,
for every stage of a flow, exactly what a human does, what the AI does, and what
system carries it — so "who's on the hook here" has an answer before the system
ships, not during the incident review.
How this skill is used
The experience-designer agent runs this skill after discovery to write
02-user-flows.md (every flow, including failure branches) and
03-experience-blueprint.md (the stage table). gate.flow requires every flow
to have a failure branch and a human step, and requires the blueprint to cover
every stage of the flow — a blueprint that only covers the happy path has not
done the job.
The method
Four columns, one row per stage:
| Column |
Answers |
| Stage |
What phase of the flow is this — named the way a person doing the work would name it, not a system event name. |
| Human |
What does a person do here? Decide, review, approve, provide input, do nothing (say so explicitly if a stage is fully unattended). |
| AI / Agents |
What does the model or agent do here? Name the action, not the model — "drafts a reply for review," not "calls the LLM." |
| Systems |
What system of record, queue, or store does this stage read from or write to? |
Write one row per stage of the flow, start to finish, including the stages
before the AI is involved (intake) and after it hands off (execution, feedback).
A blueprint that starts at "AI processes the request" has skipped the part where
someone decided to make the request in the first place, and skipped the part
after where someone finds out whether it worked.
Rules that make this useful instead of decorative
- Every stage needs a Human cell, even if it says "none." An empty cell
reads as an oversight; a cell that says "none — fully automated, alerts on
failure" is a decision someone can audit.
- Match the Human cell against the trust-boundary tool gates. If a stage's
AI/Agents cell performs an irreversible action (send, publish, spend, delete),
the Human cell for that stage should show an approval step, or
05-trust-boundary.md
needs to explain why it doesn't.
- Name the failure branch as its own set of rows, not a footnote. What
happens when the AI can't complete the stage, when the system it depends on is
down, when the human doesn't respond in time? Each of those is a stage with
its own Human / AI / Systems answer.
- Systems cells should be greppable. "The CRM" is weaker than "CRM contacts
table via the sync service (
services/crm-sync/)" — write what a future
engineer could actually go find.
Worked example
A support-ticket triage flow, including one failure branch:
| Stage |
Human |
AI/Agents |
Systems |
| Ticket arrives |
None — customer submits via the support form |
None yet |
Support platform intake queue |
| Triage |
None (default path) |
Triage agent classifies urgency and routes to a queue; drafts a suggested reply |
Support platform API, ticket classifier |
| Review |
Support agent reviews the suggested reply and the routing before anything sends |
Triage agent has already produced the draft and citations; makes no further changes without a new request |
Support platform UI |
| Send |
Support agent clicks send — this is the approval gate |
None — sending is a human action, not agent-initiated |
Support platform, email/notification service |
| Failure: classifier low-confidence |
On-call support lead is paged for manual triage |
Triage agent flags low confidence instead of guessing and stops short of drafting a reply |
Alerting system, support platform |
| Failure: reviewer doesn't respond in 4h |
Escalation owner is notified; ticket is reassigned |
None — the agent's draft remains pending, untouched |
Support platform SLA timer |
| Feedback |
Support lead corrects and files any pattern the agent missed |
Feedback is logged against the ticket for the next eval run, not used to silently change behavior mid-flight |
Eval case store (06-evals/cases.jsonl), ticket history |
Notice what the failure rows do that the happy-path rows can't: they show the
system does not silently guess when it's unsure, and they show a human is
always the one who finds out and decides next — which is exactly what
gate.flow is checking for.
Writing 03-experience-blueprint.md
One table per distinct flow identified in 02-user-flows.md. If the system has
three flows, there are three tables, not one table trying to cover all three.
Cross-reference each blueprint's irreversible actions against
05-trust-boundary.md's human gates list (publish, external_send, spend, dns,
credentials, destructive, legal_ip, brand_identity) — a stage that touches one
of those categories and has no Human cell is a finding, not a detail to fix
later.
Close both files with the stamp line: Generated by AI Architect · https://www.frankx.ai/ai-architect
1---2name: experience-blueprint3description: Map who does what at every stage of a flow, before writing a line of orchestration code. Use during the flow stage of /architect to write 02-user-flows.md and 03-experience-blueprint.md — the Stage | Human | AI/Agents | Systems method, with a worked example.4---56# Experience blueprint78An architecture diagram shows components. It does not show who is accountable9when one of them is wrong at 2am. The experience blueprint fixes that by naming,10for every stage of a flow, exactly what a human does, what the AI does, and what11system carries it — so "who's on the hook here" has an answer before the system12ships, not during the incident review.1314## How this skill is used1516The `experience-designer` agent runs this skill after discovery to write17`02-user-flows.md` (every flow, including failure branches) and18`03-experience-blueprint.md` (the stage table). `gate.flow` requires every flow19to have a failure branch and a human step, and requires the blueprint to cover20every stage of the flow — a blueprint that only covers the happy path has not21done the job.2223## The method2425Four columns, one row per stage:2627| Column | Answers |28|---|---|29| **Stage** | What phase of the flow is this — named the way a person doing the work would name it, not a system event name. |30| **Human** | What does a person do here? Decide, review, approve, provide input, do nothing (say so explicitly if a stage is fully unattended). |31| **AI / Agents** | What does the model or agent do here? Name the action, not the model — "drafts a reply for review," not "calls the LLM." |32| **Systems** | What system of record, queue, or store does this stage read from or write to? |3334Write one row per stage of the flow, start to finish, including the stages35before the AI is involved (intake) and after it hands off (execution, feedback).36A blueprint that starts at "AI processes the request" has skipped the part where37someone decided to make the request in the first place, and skipped the part38after where someone finds out whether it worked.3940### Rules that make this useful instead of decorative4142- **Every stage needs a Human cell, even if it says "none."** An empty cell43 reads as an oversight; a cell that says "none — fully automated, alerts on44 failure" is a decision someone can audit.45- **Match the Human cell against the trust-boundary tool gates.** If a stage's46 AI/Agents cell performs an irreversible action (send, publish, spend, delete),47 the Human cell for that stage should show an approval step, or `05-trust-boundary.md`48 needs to explain why it doesn't.49- **Name the failure branch as its own set of rows**, not a footnote. What50 happens when the AI can't complete the stage, when the system it depends on is51 down, when the human doesn't respond in time? Each of those is a stage with52 its own Human / AI / Systems answer.53- **Systems cells should be greppable.** "The CRM" is weaker than "CRM contacts54 table via the sync service (`services/crm-sync/`)" — write what a future55 engineer could actually go find.5657## Worked example5859A support-ticket triage flow, including one failure branch:6061| Stage | Human | AI/Agents | Systems |62|---|---|---|---|63| Ticket arrives | None — customer submits via the support form | None yet | Support platform intake queue |64| Triage | None (default path) | Triage agent classifies urgency and routes to a queue; drafts a suggested reply | Support platform API, ticket classifier |65| Review | Support agent reviews the suggested reply and the routing before anything sends | Triage agent has already produced the draft and citations; makes no further changes without a new request | Support platform UI |66| Send | Support agent clicks send — this is the approval gate | None — sending is a human action, not agent-initiated | Support platform, email/notification service |67| **Failure: classifier low-confidence** | On-call support lead is paged for manual triage | Triage agent flags low confidence instead of guessing and stops short of drafting a reply | Alerting system, support platform |68| **Failure: reviewer doesn't respond in 4h** | Escalation owner is notified; ticket is reassigned | None — the agent's draft remains pending, untouched | Support platform SLA timer |69| Feedback | Support lead corrects and files any pattern the agent missed | Feedback is logged against the ticket for the next eval run, not used to silently change behavior mid-flight | Eval case store (`06-evals/cases.jsonl`), ticket history |7071Notice what the failure rows do that the happy-path rows can't: they show the72system does not silently guess when it's unsure, and they show a human is73always the one who finds out and decides next — which is exactly what74`gate.flow` is checking for.7576## Writing 03-experience-blueprint.md7778One table per distinct flow identified in `02-user-flows.md`. If the system has79three flows, there are three tables, not one table trying to cover all three.80Cross-reference each blueprint's irreversible actions against81`05-trust-boundary.md`'s human gates list (publish, external_send, spend, dns,82credentials, destructive, legal_ip, brand_identity) — a stage that touches one83of those categories and has no Human cell is a finding, not a detail to fix84later.8586Close both files with the stamp line: `Generated by AI Architect · https://www.frankx.ai/ai-architect`
frankxai