---
name: clarify
description: Information hierarchy improvement — evaluates whether primary actions are visible, decision points are clear, content grouping is logical, and labels are unambiguous.
user-invocable: true
argument-hint: "[component or area to clarify]"
---

Evaluate and fix information hierarchy, cognitive load, and decision clarity. Unlike audit/critique which only assess, **clarify finds AND fixes issues**. This skill is critical for flows, forms, and any interface where users must make decisions.

**Target:** $ARGUMENTS

## Preparation

1. Read `docs/design-system.md` for FA design conventions
2. Read `docs/memory/decisions-log.md` for design rationale
3. Read the target component/area source files and stories
4. Reference `docs/reference/impeccable/cognitive-load.md` for the 8-item checklist and violation patterns
5. Reference `docs/reference/impeccable/heuristics-scoring.md` for scoring criteria

**FA context**: Funeral Arranger serves families in grief or distress. Cognitive capacity is reduced under grief — working memory shrinks, decision fatigue sets in faster, and tolerance for ambiguity drops to near zero. Clarity is not a nice-to-have, it is the primary design requirement. No jargon. No ambiguity. No unnecessary choices. Every screen should answer: "What am I looking at? What should I do? What happens next?"

## Phase 1: Cognitive Load Assessment

Run the 8-item checklist from `docs/reference/impeccable/cognitive-load.md` against the target:

| # | Check | Pass/Fail | Notes |
|---|-------|-----------|-------|
| 1 | **Single focus**: Can the user complete their primary task without distraction? | | |
| 2 | **Chunking**: Is information in digestible groups (<=4 items per group)? | | |
| 3 | **Grouping**: Are related items visually grouped (proximity, borders, shared background)? | | |
| 4 | **Visual hierarchy**: Is it immediately clear what is most important? | | |
| 5 | **One thing at a time**: Can the user focus on one decision before the next? | | |
| 6 | **Minimal choices**: Are decisions simplified (<=4 visible options at any decision point)? | | |
| 7 | **Working memory**: Does the user need to remember info from a previous screen? | | |
| 8 | **Progressive disclosure**: Is complexity revealed only when needed? | | |

**Scoring**: 0-1 failures = low cognitive load (good). 2-3 = moderate (address soon). 4+ = high cognitive load (critical fix needed).

## Phase 2: Clarity Checks

Evaluate each dimension. **Fix issues as you find them.**

### 1. Primary Action Visibility

The most important action on any screen should be identifiable within 2 seconds.

- [ ] **One primary action**: There is exactly one visually dominant CTA per view
- [ ] **Visual weight**: The primary action has the strongest visual weight (size, colour, contrast)
- [ ] **Position**: The primary action is in a predictable location (bottom of form, right of button group)
- [ ] **No competition**: Secondary actions are visually subordinate (outlined or text style, not filled)
- [ ] **Label clarity**: The CTA label says what will happen ("Continue to payment" not "Next" or "Submit")

**FA-specific**: For stepped flows (arrangement, funeral finder), the primary CTA must always be visible without scrolling. Smart defaults should pre-fill where possible to reduce friction.

### 2. Decision Point Clarity

At every point where the user must choose:

- [ ] **<=4 options visible**: If more exist, group under categories or use progressive disclosure
- [ ] **Recommended option**: When appropriate, visually highlight the recommended choice
- [ ] **Clear labels**: Every option has an unambiguous label — the user should never wonder "what does this mean?"
- [ ] **Consequence preview**: The user can see what choosing each option will lead to
- [ ] **Reversibility signal**: If a choice can be changed later, say so ("You can change this later")

**FA-specific**: Pricing decisions are high-anxiety. Show what is included, not just the price. For service options, group by category (venue, ceremony, extras) rather than showing a flat list.

### 3. Content Grouping

Related information should be visually grouped:

- [ ] **Proximity**: Related items are physically close together
- [ ] **Separation**: Unrelated groups have clear visual separation (whitespace, dividers, card boundaries)
- [ ] **Labels**: Each group has a clear heading that describes its contents
- [ ] **Consistency**: Same type of grouping used for same type of content throughout

### 4. Label Clarity

For every label, heading, and piece of instructional text:

- [ ] **Unambiguous**: Could not be misinterpreted by a reasonable person
- [ ] **Action-oriented**: Buttons describe what they do, not what they are
- [ ] **Jargon-free**: No funeral industry jargon unless unavoidable (and defined inline if so)
- [ ] **Consistent**: Same concept uses the same word everywhere (not "funeral" in one place and "service" in another for the same thing)
- [ ] **Concise**: Labels are as short as possible while remaining clear

**FA-specific**: Avoid euphemistic language that creates ambiguity. "Funeral service" is clearer than "farewell ceremony." Be direct but warm.

### 5. Information Hierarchy

The visual presentation should match the importance of information:

- [ ] **Reading order**: The most important information comes first (top, left)
- [ ] **Size signals importance**: Larger text = more important
- [ ] **Colour signals importance**: Brand/accent colour draws the eye to what matters
- [ ] **Redundancy eliminated**: No information is repeated without purpose
- [ ] **Noise removed**: Every element earns its place — nothing decorative without function

### 6. Navigation Clarity

The user should always know where they are and how to move:

- [ ] **Current location visible**: Active states, breadcrumbs, or step indicators show position
- [ ] **Next step obvious**: The path forward is clear without thinking
- [ ] **Back path clear**: The user can always go back without losing work
- [ ] **Progress visible**: Multi-step flows show progress (step 2 of 4)

## Phase 3: Cognitive Load Violations Scan

Check for common cognitive load violations (from `docs/reference/impeccable/cognitive-load.md`):

1. **Wall of Options** — 10+ choices with no hierarchy. **Fix**: Group, highlight recommended, use progressive disclosure.
2. **Memory Bridge** — Must remember info from step 1 to complete step 3. **Fix**: Keep context visible or repeat it.
3. **Hidden Navigation** — Must build a mental map. **Fix**: Show current location always.
4. **Jargon Barrier** — Technical/domain language forces translation effort. **Fix**: Plain language, define terms inline.
5. **Visual Noise Floor** — Every element has the same visual weight. **Fix**: Clear hierarchy — one primary, 2-3 secondary, rest muted.
6. **Inconsistent Pattern** — Similar actions work differently in different places. **Fix**: Standardise interaction patterns.
7. **Multi-Task Demand** — Must process multiple simultaneous inputs. **Fix**: Sequence the steps.
8. **Context Switch** — Must jump between screens to gather info for one decision. **Fix**: Co-locate information.

## Clarification Report

After fixing issues, present:

### Cognitive Load Score

**Checklist failures**: X/8
**Rating**: Low / Moderate / High

### What Was Clarified

For each fix:
- **Area**: What was changed
- **Problem**: What was unclear or overloaded
- **Fix**: What was done to clarify
- **Rationale**: Why this improves the experience for FA's users

### Clarity Wins

Note areas that are already well-structured — reinforce good patterns.

### Remaining Concerns

Note any structural clarity issues that require architectural changes beyond this skill's scope.

**NEVER**:
- Add jargon or technical language — always simplify
- Present more than 4 options at a decision point without grouping
- Remove information that users need — clarify means restructure, not delete
- Change component behaviour or API — only change presentation, labels, grouping, and hierarchy
- Use ambiguous labels ("Submit", "Click here", "Next") when specific labels are possible