payoff-action-modeling

What this skill does

# Outcome Action Modeling

Use this skill before designing or polishing any UI state where the user has achieved a meaningful outcome and now needs to understand what happened, what exists, and what to do next.

This applies to AI products, CRUD systems, dashboards, onboarding flows, imports, uploads, reporting tools, automation tools, admin panels, PM tools, CMS platforms, deployment or sync flows, collaborative review systems, and workflow products.

The goal is to answer: "Now that the user has value or progress, what might they reasonably want to do next, and where should each action live?"

## Core Output

Produce an action model with:

- `Primary outcome`: the result, resource, state, or completion the user should understand first.
- `Outcome state type`: `completion`, `generation`, `workspace`, `review`, `handoff`, `recovery`, or `continuation`.
- `User questions`: realistic "What if I want to..." questions from the user's point of view.
- `Action scope`: `outcome`, `selection`, `item`, `continuation`, `navigation`, `recovery`, or `assistance`.
- `Intent pressure`: `immediate`, `contextual`, or `deferred`.
- `UI placement`: `primary CTA`, `secondary action`, `per-item action`, `row menu`, `accordion detail`, `bulk toolbar`, `empty/optional state`, `status area`, `shell navigation`, or `next screen`.
- `Required vs optional`: whether the action must be visible now or can be deferred.
- `Copy`: short labels written as user-facing outcomes, not implementation details.

Use this table shape unless the user requests another format:

| User question | Scope | Pressure | Action | Placement | Required? | Label |
| --- | --- | --- | --- | --- | --- | --- |
| How do I open one item? | item | contextual | open item details | per-item action | yes, if item inspection matters | Open |
| How do I act on everything? | outcome | immediate | apply action to full result | primary CTA | yes | Download all |
| How do I recover a removed item? | recovery | deferred | restore from history | secondary action or history screen | yes, if removal exists | Restore |

## Outcome State Types

Classify the screen before placing actions:

| Type | Description |
| --- | --- |
| completion | The user finished a flow, setup, onboarding step, task, approval, or configuration. |
| generation | The system produced a result such as test cases, content, analysis, recommendations, or files. |
| workspace | The user now continues work inside a project, dashboard, editor, board, list, or admin surface. |
| review | The user validates, approves, rejects, compares, comments on, or verifies an outcome. |
| handoff | The user exports, shares, publishes, transfers, downloads, syncs, or sends the outcome elsewhere. |
| recovery | The user fixes, retries, restores, rolls back, resolves errors, or undoes changes. |
| continuation | The user extends the workflow, creates more, repeats with different inputs, or starts the next branch. |

## Principles

### Outcome Clarity

The user should understand within about two seconds:

- what happened
- what was created, completed, imported, deployed, synced, approved, or changed
- what the highest-value next action is
- where to inspect details before acting

### Locality Principle

Actions should appear near the object they affect.

- Item actions belong near rows, cards, files, cases, records, comments, tasks, or list items.
- Selection actions belong in a toolbar that appears after selection exists.
- Destructive actions should remain contextual and recoverable.
- Refinement, help, explanation, and AI actions should appear beside the object being refined or explained.
- Full-result actions belong near the outcome summary or primary completion area.

### Intent Pressure

Classify actions by urgency:

- `immediate`: the user probably needs this action now to capture value or finish the job.
- `contextual`: the action matters when the user is inspecting a specific object, state, error, or selection.
- `deferred`: the action is useful but should not compete with the primary outcome moment.

Rules:

- Immediate actions dominate the outcome state.
- Contextual actions stay close to their object.
- Deferred actions can live behind secondary controls, menus, details, settings, or later screens.
- Advanced actions should not overload first-success moments.

### Action Density Management

Avoid overwhelming users immediately after success or completion.

- Prefer one clear primary action over multiple equal CTAs.
- Keep toolbars compact until selection, filtering, review, or edit mode makes them necessary.
- Do not stack continuation prompts, refinement tools, upgrade prompts, and export options in the same visual tier.
- Show enough actions to support momentum, but not so many that the outcome becomes secondary to tooling.

### Momentum Continuation

The UI should answer: "How does the user continue naturally after achieving value?"

- Continuation actions should extend momentum without replacing the primary success state.
- `Create another`, `Generate more`, `Import more`, `Add teammate`, `Publish`, `Run again`, `Open workspace`, and `Review next` should be optional branches.
- Do not make continuation mandatory after success unless the product flow truly requires it.
- Preserve the current result while letting the user branch, repeat, refine, or hand off.

### Scope Separation

Keep these scopes distinct in label, placement, and behavior:

- one-item actions
- multi-item or selected-item actions
- full-result actions
- continuation actions
- navigation actions
- recovery actions
- assistance actions

If users cannot tell whether an action affects one item, selected items, or everything, the action model is not done.

## Workflow

1. Define the outcome.
   - State the result, resource, completed step, imported data, deployment, sync, report, automation, or review state in plain language.
   - State what "success" means for the user.
   - Identify whether the screen is a first-success moment, production workspace, review state, handoff state, recovery state, or continuation branch.

2. Ask user-intent questions.
   - Generate 12-25 questions from the user's point of view.
   - Prefer concrete questions over abstract needs.
   - Include one-item, selected-item, full-result, continuation, navigation, recovery, collaboration, validation, and assistance questions.

3. Classify action scope.
   - `outcome`: affects the full result, resource set, completed flow, report, upload, import, deployment, or sync.
   - `selection`: affects multiple chosen objects or resources.
   - `item`: affects one row, card, file, record, task, case, page, comment, or resource.
   - `continuation`: extends, repeats, branches, adds to, or continues the workflow.
   - `navigation`: moves across screens, workspaces, dashboards, sources, projects, or settings.
   - `recovery`: supports undo, retry, restore, compare, history, rollback, discard, or error repair.
   - `assistance`: supports help, explanation, AI refinement, recommendations, support, or guided improvement.

4. Classify intent pressure.
   - Mark actions as `immediate`, `contextual`, or `deferred`.
   - Let immediate actions shape the first visual hierarchy.
   - Keep contextual actions local to their object.
   - Move deferred actions to secondary placement unless hiding them would block trust, safety, or completion.

5. Place actions by scope.
   - Put the highest-value full-outcome action in the primary CTA.
   - Put per-item actions inside the item row, card, accordion, panel, preview, or menu.
   - Put selection actions in a bulk toolbar that appears after items are selected.
   - Put continuation actions as optional next branches, not required completion steps.
   - Put navigation actions in the shell, breadcrumb, footer, completion area, or next screen.
   - Put recovery actions near the state they recover from, with visible confirmation after destructive or risky actions.
   - Put assistance near the object, result,