# Shaped Brief

**Illustrative sample for portfolio use**  
Generalized scenario based on a merchant payouts workflow.

## Document profile

| Field | Value |
|---|---|
| Framework node | Shaping & Delivery |
| Document role | Turn an approved direction into delivery-ready work |
| Working title | Merchant payout status visibility |
| Owner | Product Owner |
| Last updated | 2026-04-07 |
| Status | Ready for delivery intake |

## 1. Objective

Introduce a first merchant-facing payout status model inside the product so that merchants can understand whether a payout is:
- processing normally
- waiting for internal review
- completed
- failed
- requiring action

## 2. Scope for release one

### In scope
- new external payout status labels
- short explanatory helper text for each visible state
- display update in merchant payout detail view
- fallback behavior for unsupported internal states
- event logging for status visibility checks

### Not in scope
- email notifications
- redesign of full payouts history
- new payout engine logic
- changes to manual review policy

## 3. User-facing status model

| Merchant-facing state | Meaning | User implication |
|---|---|---|
| Processing | The payout was accepted and is still moving through the normal flow | No action required |
| In review | The payout needs an internal check before it can continue | Wait for update |
| Completed | The payout finished successfully | No action required |
| Failed | The payout could not be completed | Review reason and retry if applicable |
| Action required | Additional input or correction is needed before the payout can proceed | Merchant action needed |

## 4. Delivery notes

- Internal source statuses remain unchanged.
- Product maps internal states to a reduced merchant-facing set.
- Copy should explain next-step meaning, not internal mechanics.
- Unknown or unsupported internal states should fall back to a safe default and be logged.

## 5. Acceptance criteria

1. Merchant sees one clear payout state in the payout detail view.
2. Each state has short supporting copy written in plain language.
3. Internal statuses are mapped to one merchant-facing state through an explicit rule set.
4. Unsupported internal statuses do not break the payout detail screen.
5. Events are logged when the payout detail view is opened for measured states.
6. Support and operations review the visible copy before release.

## 6. Dependencies

| Area | Need |
|---|---|
| Operations | validation of safe external language |
| Engineering | status mapping implementation and fallback handling |
| Analytics | event naming and baseline tracking |
| Support | review of user-facing wording and expected escalation impact |

## 7. Delivery readiness checklist

- [x] Problem is defined
- [x] Decision is approved
- [x] First release scope is bounded
- [x] User-facing states are named
- [x] Acceptance criteria are explicit
- [ ] Copy reviewed by support and operations
- [ ] Final mapping table confirmed with engineering

## 8. Suggested Jira / delivery structure

- Epic: Merchant payout status visibility
- Story 1: Map internal payout statuses to external states
- Story 2: Update payout detail UI with status label and helper text
- Story 3: Add analytics event for payout detail state visibility
- Task: Validate fallback behavior for unsupported states
- Task: Review copy with support and operations

## 9. Related artifacts

- Problem Brief
- Decision Brief
- Outcome Review