Parsons/.claude/skills/clarify/SKILL.md

name, description, user-invocable, argument-hint

name	description	user-invocable	argument-hint
clarify	Information hierarchy improvement — evaluates whether primary actions are visible, decision points are clear, content grouping is logical, and labels are unambiguous.	true	[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