sync: auto-sync from GURU-5070 at 2026-06-03 20:07:24

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-03 20:07:24

.claude/skills/human-flow/references/report-template.md

@@ -0,0 +1,86 @@
+# Human-Flow Report Template
+
+Use this structure for all `scan`, `audit`, and `report` outputs.
+
+---
+
+## Human-Flow Report: <Target / Component / Page>
+
+**Date**: YYYY-MM-DD  
+**Scanner**: human-flow v1 (mouse + keyboard intuition focus)  
+**Scope**: <files/components scanned>  
+**Overall Human Workflow Score**: X/10  
+- Mouse Ergonomics: X/10  
+- Keyboard Parity & Efficiency: X/10  
+- Workflow Discoverability & Friction: X/10  
+
+**Summary**  
+(2-4 sentences: the biggest sources of unintuitive behavior for a human operator using mouse and keyboard, and the net effect on daily workflow.)
+
+### High Friction (P0 — fix before broader use)
+List the most damaging issues for frequent tasks.
+
+#### Issue 1 — Severity: high (mouse + keyboard)
+- **Location**: `path/to/file.tsx:42` (or component + specific element)
+- **Pattern**: Hover-revealed row actions / small icon targets / missing keyboard activation / etc.
+- **Human Experience**: 
+  When scanning the Sessions list with a mouse, the Control and End buttons are dimmed until the pointer is exactly over the row. A keyboard user tabbing through never sees them at full strength. The primary action for an operator (taking control of a machine) requires extra precision and discovery.
+- **Why costly**: High-frequency task. Small miss rate + extra hover step adds up across dozens of sessions per day. Creates "hunt and hope" instead of "glance and act".
+- **Recommended improvement** (better for humans):
+  - Make actions at least 70-80% opacity at rest (or always fully visible in a dedicated column).
+  - Ensure the primary action (Control/View) is the strongest visual target and also activates on row click + Enter.
+  - Add explicit `aria-label` + visible focus treatment.
+  - Example pattern: always-visible ghost buttons with generous hit area + row click as power-user shortcut.
+
+#### Issue 2 — ...
+
+### Medium Friction (P1)
+...
+
+### Low / Polish (P2)
+...
+
+### Strengths (things that already feel good for humans)
+- ...
+
+### Fancy / Delight Opportunities (from `fancy` pass)
+This section only appears when the `fancy` command/mode is run.
+
+**Appropriateness verdict**: [Highly appropriate / Appropriate with restraint / Better kept minimal / Not appropriate for this surface]
+
+#### Delight Idea 1 — Category: micro-interaction / transition / loading / etc.
+- **Location**: ...
+- **Current state**: ...
+- **Opportunity**: A tasteful [specific elegant behavior] would make this interaction feel more premium and responsive.
+- **Why it fits (or doesn't)**: ...
+- **Suggested implementation notes**: ...
+- **Reduced-motion fallback**: ...
+
+(Repeat for 2–5 highest-leverage ideas. Be ruthless — only suggest things that genuinely elevate without adding noise.)
+
+### Recommended Next Steps
+1. ...
+2. ...
+
+**Notes for implementation**:
+- Any change here should be validated with both `frontend-design` visual checklist and this scanner afterward.
+- Consider adding a small set of visible keyboard shortcuts for the top 2-3 actions and surface them in the UI (e.g. in a help footer or on hover of the main button).
+- After making fancy changes, re-run `human-flow fancy` to check that the additions feel intentional rather than tacked-on.
+
+---
+
+## Quick Reference for Common Fixes
+
+**Small targets** → Increase min size + padding. Use the generous wrapper pattern.
+
+**Hover-only actions** → Raise resting opacity or move to always-visible "Actions" area. Never rely on hover for primary or frequent actions.
+
+**Mouse-only activation** → Add `tabIndex`, `onKeyDown` for Enter/Space, strong `:focus-visible`, and `aria-*` labels.
+
+**Weak feedback** → Add immediate `:active`/loading state, row highlight on selection, and clear disabled messaging.
+
+**Precision-heavy workflows** → Widen hit areas, reduce number of steps, make the "obvious next thing" the biggest target.
+
+---
+
+*This template is intentionally human-first in language. Every finding must explain the lived experience of a person with a mouse and keyboard, not just the code smell.*