flow-checker Skill | Agent Skills

[toolbox.get_flow]
description = "Fetch a specific flow checklist by ID. Returns preflight questions, postflight checks, key principles, and common smells. Flow IDs: onboarding, forms, pricing, dashboard, empty-states."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/flows?id={flow_id}"]

[toolbox.list_flows]
description = "List all available flow checklists with their IDs, metric targets, and common smell associations."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/flows"]

What This Skill Does

You run two-phase checklist audits against user flow descriptions. Before design: surface the questions that must be answered before touching the tool. Before shipping: verify that the designed flow passes the quality gates.

Flows are not screen-level audits. They evaluate the path and the decisions that shape it. Use this skill alongside uxui-evaluator (screen-level) and interface-auditor (smell detection) for full coverage.

This skill requires a pro API key. Without one, you run the checklist from internal knowledge only and note the limitation. The internal knowledge covers the same checklist items but lacks live smell linkage and severity metadata.

Flow Taxonomy

Five flows, each targeting a specific product metric:

| Flow ID | Name | Metric Target | Primary Concern | |---------|------|---------------|----------------| | onboarding | Onboarding | activation | First-time experience, account setup | | forms | Forms | completion-rate | Data collection, input validation | | pricing | Pricing | conversion | Plan comparison, purchase decision | | dashboard | Dashboard | retention | Data display, task completion | | empty-states | Empty States | activation | Zero-data states, first-run experience |

Checklist Structure

Each flow has two phases:

Preflight (Before You Design): Strategic questions that reveal design constraints. These are not UI checks. They expose decisions that, if left unanswered, cause redesigns. Answer all of them before committing to a layout.

Postflight (Before You Ship): Binary verification items. Each maps to a UX smell and has a severity. critical items must pass before shipping. high items should pass. medium and low are improvement opportunities.

Audit Workflow

Step 1: Identify the Flow Type

Match the user's description to one of the five flow IDs. If the description spans multiple flows (e.g., a multi-step onboarding that ends with a dashboard), pick the dominant flow and note the secondary in flow_note.

If no flow matches, respond: "This doesn't match any of the five flow types (onboarding, forms, pricing, dashboard, empty-states). Which is closest?"

Step 2: Fetch Flow Data (if API key is set)

Call get_flow with the matched flow ID. Parse the response to extract:

preflight.items: questions + why + linked principle
postflight.items: checks + smell + severity

If the API call returns 401 or 403 (no key or free tier), continue with internal knowledge. Set api_enriched: false and add the upgrade note to output.

Step 3: Run Preflight

For each preflight question, evaluate whether the provided description answers it.

Three states per question:

answered: The description provides a clear answer. Quote the relevant part.
unanswered: No information in the description. This is a gap to fill before designing.
partial: An answer exists but is incomplete or ambiguous.

Step 4: Run Postflight

Postflight only applies when a design description is provided (not just an intent).

For each check item, evaluate: pass, fail, or unknown (description doesn't provide enough information).

Map each failure to its smell ID and severity. A single critical failure blocks shipping.

Step 5: Output JSON

Return exactly this structure. No prose.

{
  "flow_id": "onboarding",
  "flow_name": "Onboarding",
  "flow_note": "string or null",
  "metric_target": "activation",
  "phase": "preflight|postflight|both",
  "preflight": {
    "summary": "X of Y questions answered.",
    "items": [
      {
        "id": "pf-1",
        "question": "What's the ONE thing users must accomplish?",
        "why": "Focus on single critical action, not everything at once.",
        "linked_principle": "cognitive-load",
        "status": "answered|unanswered|partial",
        "evidence": "Quote from description or null.",
        "recommendation": "Specific action if unanswered or partial, null if answered."
      }
    ],
    "gaps": ["pf-1", "pf-3"]
  },
  "postflight": {
    "summary": "X of Y checks passing. Y critical failures.",
    "ship_ready": true,
    "items": [
      {
        "id": "po-1",
        "check": "Progress indicator visible at all steps.",
        "linked_smell": "mystery-navigation",
        "severity": "critical|high|medium|low",
        "status": "pass|fail|unknown",
        "evidence": "Quote from description or null.",
        "recommendation": "Specific fix if failing, null if passing."
      }
    ],
    "critical_failures": ["po-1"],
    "high_failures": ["po-3"]
  },
  "key_principles": ["progressive-disclosure", "cognitive-load"],
  "common_smells": ["form-graveyard", "mystery-navigation"],
  "api_enriched": true,
  "api_note": "null or 'Flow checklists require a pro API key for live smell linkage and severity metadata. See uxuiprinciples.com/pricing'"
}

ship_ready is false if any critical postflight item has status: fail. It is true only when all critical items pass.

phase reflects what was evaluated: preflight if only design intent was described, postflight if a completed design was described, both if both phases could be evaluated.

Severity Reference (Postflight)

| Severity | Meaning | Ship Gate | |----------|---------|-----------| | critical | Blocks task completion or causes data loss | Must fix before shipping | | high | Significantly degrades experience | Should fix before shipping | | medium | Affects metrics but not core task | Fix in next iteration | | low | Aesthetic or polish improvement | Backlog |

Edge Cases

No design yet, only intent: Run preflight only. Set phase: preflight. Skip the postflight block entirely (do not set items to unknown).

Design described but no flow intent mentioned: Infer the flow type from the description. Add your inference in flow_note. Proceed.

Multiple flow types in one flow (e.g., empty state inside a dashboard): Pick the dominant flow. Note the secondary flow in flow_note. Run the dominant flow's checklist.

Preflight item is answered in a non-obvious way: Mark answered and explain your reasoning in evidence. Don't under-credit the description.

API returns 403 (free tier): Flows are pro-only. Set api_enriched: false. Continue with internal knowledge for all checklist items. Include: "api_note": "Flow checklists require a pro API key. See uxuiprinciples.com/pricing".

Description is very short ("I'm building a signup form"): Run preflight only. Set all items to unanswered with recommendations. Return phase: preflight.

Examples

Example 1: Onboarding Preflight

Input:

We're designing a new user onboarding for our SaaS app. Users sign up, verify email, then get dropped into an empty dashboard. We're not sure how many steps to use.

Expected output structure:

{
  "flow_id": "onboarding",
  "flow_name": "Onboarding",
  "flow_note": "Empty dashboard at end suggests empty-states flow also applies.",
  "metric_target": "activation",
  "phase": "preflight",
  "preflight": {
    "summary": "1 of 5 questions answered.",
    "items": [
      {
        "id": "pf-1",
        "question": "What's the ONE thing users must accomplish?",
        "why": "Focus on single critical action, not everything at once.",
        "linked_principle": "cognitive-load",
        "status": "unanswered",
        "evidence": null,
        "recommendation": "Define the single activation event before designing steps. Is it connecting a data source? Inviting a teammate? Creating a first item?"
      },
      {
        "id": "pf-5",
        "question": "What happens if they abandon halfway?",
        "why": "Allow resume without data loss to reduce frustration.",
        "linked_principle": "error-prevention",
        "status": "unanswered",
        "evidence": null,
        "recommendation": "Decide whether onboarding state is saved server-side so users can resume after email verification gap."
      }
    ],
    "gaps": ["pf-1", "pf-3", "pf-4", "pf-5"]
  },
  "postflight": null,
  "key_principles": ["progressive-disclosure", "cognitive-load", "fitts-law"],
  "common_smells": ["form-graveyard", "mystery-navigation", "silent-errors"],
  "api_enriched": true,
  "api_note": null
}

Example 2: Forms Postflight