Draft a lightweight user flow doc after a kickoff call — simplified, non-technical, readable by product leads. Use when the user wants to document user flows, create a user flow doc, or post a flow for business alignment before building.
IMPORTANT: Never auto-commit. Never auto-post to Slack without showing the doc and getting confirmation first.
After a kickoff call, before architecture. This doc is the gate that prevents building the wrong thing. It must be readable by a product lead or non-technical stakeholder.
This is leadership's complete view of the feature. There is no stakeholder section in the engineering PRD — this doc carries the full responsibility for business alignment. If something important is missing here, leadership will not see it anywhere else.
This is NOT:
It IS:
Ask the user for context:
Interview briefly to resolve gaps. Keep it lightweight — this is not $grill-me. Cover:
Explore the codebase only if you need to verify where this feature fits in the existing system. Do not go deep into implementation.
Draft the user flow doc using the template below.
Present the draft for review. Iterate until the user is happy.
After approval, format it for Slack posting:
Wait for the user's explicit "post it" confirmation before sending anything. If Linear MCP or Slack tools are in scope, the user must approve before any write action.
After posting, save the doc to Linear as a project description or issue description — this becomes the persistent record that $arch-brief will reference in a future session.
Once business alignment is confirmed, suggest $arch-brief as the next step.
2 to 3 sentences describing the problem from the user's perspective. No jargon. No references to the system. A non-technical reader should feel the pain immediately.
1 to 2 sentences on why this is the right time to build this — business context, user demand, strategic priority, or cost of delay. This is what leadership needs to justify the investment.
Bullet list of actors and their goals. One line each.
A mermaid sequence diagram showing the happy path. Use realistic names and dialogue, not abstract labels.
sequenceDiagram
actor User
participant App
User->>App: concrete action
App-->>User: concrete response
Follow with 2 to 3 sentences of plain narrative walking through the diagram with a concrete example.
If the feature has stateful objects that the user interacts with, include a mermaid flowchart of user-visible states and transitions. If not, skip this section.
flowchart LR
Draft --> Submitted --> Approved
User-visible edge cases only. Not implementation edge cases.
How will we know this feature is working? Use concrete, measurable signals — not vague goals.
Explicit non-goals. Keeps the discussion focused and prevents scope creep during review.
Things that need product input before moving to architecture.
After business approval, suggest $arch-brief to design the implementation approach.