free-pi-cli 0.6.2 → 0.6.4

package/skills/ux-walker/references/ux-audit-rubric.md

@@ -0,0 +1,174 @@
+# UX Audit Rubric
+
+Used by ux-walker to evaluate every page state encountered during story walks.
+
+## Scoring
+
+Each criterion is scored: `pass` | `warn` | `fail`
+- **pass**: Meets expectations, no action needed
+- **warn**: Minor issue, worth noting (medium/low severity finding)
+- **fail**: Clear problem, must be addressed (high/critical severity finding)
+
+## 1. Simplicity
+
+**Question**: Is the user overwhelmed?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Visible action count | ≤5 primary actions visible | 6-8 primary actions | >8 primary actions competing for attention |
+| Information density | Appropriate for the task | Some unnecessary info visible | Wall of text or data overload |
+| Decision complexity | Clear next step | Requires scanning | User must read everything to know what to do |
+| Advanced options | Hidden behind toggle/menu | Visible but de-emphasized | Mixed with primary actions |
+
+**"Take Away" Test**: For each visible element, ask: "If I removed this, would the user still succeed?" If yes, it should be hidden, collapsed, or moved to an advanced section.
+
+## 2. Progressive Disclosure
+
+**Question**: Does information appear when needed, not before?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Form fields | Show only what's needed for current step | All fields visible but grouped | Long scrolling form with everything at once |
+| Error messages | Appear on interaction/submission | Pre-shown but dimmed | Error states visible before user acts |
+| Help text | Available on hover/click | Inline but concise | Paragraphs of instructions before the action |
+| Secondary features | Revealed after primary task | Visible but clearly secondary | Competing with primary workflow |
+
+## 3. Layout Quality
+
+**Question**: Does the page use space effectively?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Viewport usage | Content fills viewport appropriately | Minor whitespace gaps | Large empty areas or content crammed in corner |
+| Scroll necessity | No unnecessary scrolling for primary task | Slight scroll needed | Must scroll to find primary action |
+| Content width | Readable line lengths (45-75 chars for text) | Slightly wide/narrow | Full-width text or extremely narrow columns |
+| Spacing consistency | Uniform spacing rhythm | Minor inconsistencies | Noticeably uneven spacing |
+| Responsive behavior | Elements reflow gracefully | Minor alignment issues at edges | Broken layout, overlapping elements |
+
+## 4. Visual Correctness
+
+**Question**: Is the page visually sound?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Overflow | No content overflow | Slight text truncation with ellipsis | Content spilling out of containers |
+| Alignment | Elements properly aligned | 1-2px misalignment | Visibly misaligned elements |
+| Theme consistency | Colors/fonts match design system | Minor deviation | Clashing styles, mixed themes |
+| Broken elements | All elements render correctly | Minor rendering artifact | Missing images, broken layouts, empty containers |
+| Z-index/layering | Proper stacking | Minor overlap on edge cases | Modals behind content, dropdowns clipped |
+
+## 5. Happy Path Clarity
+
+**Question**: Can a naive user accomplish the goal without help?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Primary CTA | Obviously the next step | Identifiable with scanning | Buried or ambiguous |
+| Labels/copy | Self-explanatory | Requires domain knowledge | Jargon, abbreviations, or misleading text |
+| Navigation | User always knows where they are | Breadcrumbs/back available but not prominent | Lost/disoriented after action |
+| Feedback | Clear success/error indication | Subtle feedback | No feedback after action |
+| Recovery | Easy to undo or go back | Can go back but not obvious | Destructive action with no undo |
+
+## 6. Accessibility Basics
+
+**Question**: Are basic accessibility needs met?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Color contrast | Meets WCAG AA (4.5:1 text, 3:1 large) | Close to threshold | Clearly insufficient contrast |
+| Interactive sizing | Touch targets ≥44x44px | 32-44px | <32px targets |
+| Focus indicators | Visible focus ring on tab | Focus visible but faint | No visible focus indicator |
+| Alt text | Images have meaningful alt text | Generic alt text | Missing alt text on informative images |
+| Keyboard nav | All actions reachable via keyboard | Most actions reachable | Key actions require mouse only |
+
+## 7. Error Handling & Edge Cases
+
+**Question**: Does the app handle problems gracefully?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Empty states | Helpful message with action suggestion | Generic "no data" message | Blank/broken appearance |
+| Loading states | Skeleton or spinner with context | Generic spinner | No loading indication, appears frozen |
+| Error messages | Specific, actionable, non-technical | Generic but polite | Technical jargon, stack traces, or cryptic codes |
+| Form validation | Inline, immediate, helpful | On submit only, but clear | Unclear what went wrong or how to fix |
+| Network failure | Retry option, data preserved | Error shown, manual refresh needed | Silent failure, data lost |
+
+## 8. Visual Consistency & Rhythm
+
+**Question**: Do repeated elements look like siblings, and does spacing follow a rhythm?
+
+Verify with the screenshot AND `geometry-audit.js` (see `visual-inspection.md`) — measured pixel numbers, not impressions.
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Sibling uniformity | Cards/tiles/rows in a group share height, width, padding, radius | ≤8px drift, or one deliberate feature member | Visibly different shapes in the same row/grid |
+| Edge alignment | Left edges and tops align across sections | 2-8px drift | Visibly misaligned columns, rows, or label/input pairs |
+| Spacing scale | Gaps come from one consistent scale (4/8px-based) | Occasional off-scale gap | Random gaps; same-level siblings spaced differently |
+| Indentation | Nested content indents uniformly, one width per level | Slight inconsistency | Mixed indent widths; nesting unreadable from indent |
+| Component consistency | The same control looks identical everywhere it appears | Minor variants (size only) | Same control styled differently across screens |
+
+## 9. Text Fit & Wrap
+
+**Question**: Does real content fit the layout without breaking it?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Control labels | Buttons/tabs/chips/nav items stay on one line | Wraps only at extreme viewport | Wrapped control label at default viewport |
+| Overflow/clipping | Text fits, or truncates with ellipsis + full value available (title/tooltip) | Tight fit, no breathing room | Clipped mid-letter, spills over container, overlaps neighbors |
+| Long content | Layout absorbs the longest realistic value (name, email, title) | Minor push | Long value blows apart a row, card, or table |
+| Wrap quality | Breaks at word boundaries; headings avoid orphan single words | — | Mid-word breaks without hyphenation |
+
+## 10. Visual Hierarchy & Redundancy
+
+**Question**: Does visual weight match importance — and is each thing said once?
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Primary action | Exactly one visually dominant action per screen | Primary findable but not dominant | Multiple competing primaries, or none |
+| Importance encoding | Size/weight/color/position track importance | Mostly consistent | Key info visually quieter than trivia |
+| Heading structure | Logical levels, one page title | Skipped level | Flat or scrambled heading hierarchy |
+| Information stated once | Each fact appears once per screen | Duplicated in header + body | Same info shown 3+ times; same control duplicated on one screen |
+| Emphasis budget | Bold/color/badges used sparingly | Some over-emphasis | Everything emphasized — nothing stands out |
+
+## 11. Flow Economy
+
+**Question**: Is this the shortest sensible path to the user's goal?
+
+Score per story (using the Flow Log), not per page. Compare against the story's **Ideal path** from the catalog when present.
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| Step count | Actual ≈ minimal conceivable | 1-2 extra steps | 3+ extra steps or forced detours |
+| Decision load | Defaults carry the user; choices only where they matter | Some unnecessary choices | User must decide things the app could infer |
+| Data re-entry | Never re-enter data the app knows | Prefilled but must re-confirm | Re-typing known data |
+| Confirmations | Only for destructive/irreversible actions | One superfluous confirm | Confirmation chains on safe actions |
+| Dead ends | Every screen offers the obvious next step | Exit via back button only | User stranded; must restart from home |
+| One way per task | One clear route (plus deliberate shortcuts) | Two unmarked equivalent routes | Multiple divergent routes with different results |
+
+## Finding Template
+
+When a check results in `warn` or `fail`, create a finding:
+
+```json
+{
+  "id": "F-{STORY_ID}-{SEQ}",
+  "severity": "critical|high|medium|low|suggestion",
+  "category": "simplicity|disclosure|layout|visual|consistency|hierarchy|flow|happy-path|a11y|error-handling",
+  "criterion": "Which specific check failed",
+  "score": "warn|fail",
+  "description": "What is wrong",
+  "expected": "What should happen",
+  "actual": "What actually happens",
+  "screenshot": "path/to/screenshot.png",
+  "suggested_fix": "How to fix it (if obvious)",
+  "files_likely_involved": ["src/components/Foo.tsx"]
+}
+```
+
+## Severity Mapping
+
+- **critical**: App crashes, data loss, completely blocked workflow, security issue
+- **high**: User cannot complete primary goal, major visual breakage, misleading UI
+- **medium**: Annoying but workaround exists, moderate visual issues, confusing copy
+- **low**: Minor cosmetic issue, slight inconvenience, polish item
+- **suggestion**: Enhancement idea, not a bug ("this would be even better if...")

package/skills/ux-walker/references/visual-inspection.md

@@ -0,0 +1,92 @@
+# Visual inspection protocol
+
+How to catch what an accessibility snapshot cannot: misalignment, uneven shapes,
+bad spacing, broken wrapping. Use two instruments together.
+
+- **Vision (look_at_image)**: judges the overall look. Is it balanced, intentional,
+  clear? It is poor at exact pixel values and can be wrong.
+- **Geometry script (`geometry-audit.js`)**: measures exact heights, gaps, drift and
+  spill. Numbers are reliable, but they cannot tell whether a difference is intended.
+
+A finding needs both: the script (or your own measurement) shows the defect, and the
+screenshot shows a user would notice it. Prefer the script for anything measurable.
+
+## Budget
+
+Each look_at_image call uses part of the user's daily allowance. Make one call per
+distinct page state (a new page or a major layout change), not per click. Ask one
+specific question per call. Never ask about the same image twice. The mobile check
+gets one call per story at most. If an answer disagrees with the measurements, trust
+the measurements.
+
+## The look pass
+
+Save the screenshot inside the project folder, then:
+
+```
+look_at_image(path="docs/ux-walker/shots/STORY-007/step-3.png",
+  question="List what you see on this screen, then answer yes/no with the element names: (1) Do repeated cards, tiles or rows differ in height, width, radius or padding? (2) Do left edges and tops that should line up actually line up? (3) Are gaps between siblings equal? (4) Is any button, tab or chip label wrapped onto two lines, cut off, or overflowing its container? (5) Which single element looks like the primary action, and is it clearly the most prominent? (6) Is any fact shown more than once?")
+```
+
+Adapt the question to the screen. Keep it under about 100 words and make it concrete.
+Record one sentence per screenshot in walk-report.md: what the screen shows, and what
+failed the look pass.
+
+## The measure pass
+
+Run at each distinct page state:
+
+```bash
+agent-browser --session $S eval --stdin < "$SKILL_DIR/references/geometry-audit.js"
+```
+
+Output is JSON:
+
+| Field | Meaning | Typical finding |
+|-------|---------|-----------------|
+| `pageOverflowX` | px of horizontal page scroll | `layout`: something is wider than the viewport |
+| `unevenRows[]` | similar siblings in one row with mismatched `heights`, `widths`, `gaps` or `topDriftPx` | `consistency`: cards with different shapes, uneven gutters |
+| `overflowSpills[]` | content escaping a container with `overflow: visible` | `layout`: text or element spilling out |
+| `wrappedControls[]` | short control labels forced onto 2+ lines | `layout`: wrapped button or tab labels |
+
+Rules:
+- Confirm each script hit in the screenshot (or with `get box`) before logging it.
+  Skip it if the variance is deliberate, such as a featured card.
+- Thresholds already skip small noise (more than 8px shape variance, 4px gap variance,
+  3px top drift). Do not report smaller differences.
+- One systemic defect is one finding. If the same card is uneven on five screens, log
+  one finding that lists all five.
+
+## Ad-hoc measurements
+
+```bash
+agent-browser --session $S get box "<selector>"
+agent-browser --session $S get styles "<selector>"
+```
+
+Compare two boxes to prove a misalignment. Findings with numbers ("left edges differ
+by 7px: 24px vs 31px") get fixed; "looks slightly off" gets ignored.
+
+## Responsive spot-check
+
+Once per story, on its main screen:
+
+```bash
+agent-browser --session $S set viewport 390 844
+agent-browser --session $S screenshot docs/ux-walker/shots/<story>/mobile-check.png
+agent-browser --session $S eval --stdin < "$SKILL_DIR/references/geometry-audit.js"
+agent-browser --session $S set viewport 1280 800
+```
+
+The script usually finds wrap and overflow problems at narrow width first. Use the one
+look_at_image call only if the script reports something or the page looks unusual.
+
+## Theme spot-check (only if the app has dark and light modes)
+
+```bash
+agent-browser --session $S set media dark
+agent-browser --session $S screenshot docs/ux-walker/shots/<story>/dark-check.png
+agent-browser --session $S set media light
+```
+
+Look for unreadable text, hard-coded light backgrounds and invisible borders.

package/skills/ux-walker/templates/latest-report-template.md

@@ -0,0 +1,139 @@
+# UX Walker Run Report — Template
+
+This template is used in the report step to generate `docs/ux-walker/latest-report.md`.
+
+---
+
+```markdown
+# UX Walker Report — {DATE}
+
+## Run Summary
+
+| Metric | Value |
+|--------|-------|
+| **Target URL** | {URL} |
+| **Run mode** | {full / incremental / focused on "{TOPIC}"} |
+| **Stories in catalog** | {TOTAL} |
+| **Stories walked** | {WALKED} |
+| **Stories skipped** | {SKIPPED} (passed previously, no changes) |
+| **Stories re-verified** | {REVERIFIED} |
+| **Overall pass rate** | {PASSED}/{WALKED} ({PERCENT}%) |
+| **Duration** | {DURATION} |
+
+## Findings Summary
+
+### By Severity
+
+| Severity | Count | Quick Fixed | Issue Filed | Deferred |
+|----------|-------|-------------|-------------|----------|
+| Critical | {N} | {N} | {N} | {N} |
+| High | {N} | {N} | {N} | {N} |
+| Medium | {N} | {N} | {N} | {N} |
+| Low | {N} | {N} | {N} | {N} |
+| Suggestion | {N} | — | — | {N} |
+| **Total** | **{N}** | **{N}** | **{N}** | **{N}** |
+
+### By Category
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| Simplicity | {N} | {brief example} |
+| Disclosure | {N} | {brief example} |
+| Layout | {N} | {brief example} |
+| Visual | {N} | {brief example} |
+| Happy Path | {N} | {brief example} |
+| Accessibility | {N} | {brief example} |
+| Error Handling | {N} | {brief example} |
+
+## Quick Fixes Applied
+
+{For each fix:}
+
+### {FINDING_ID}: {Short Description}
+- **Story**: STORY-{ID} — "{Title}"
+- **What was wrong**: {description}
+- **Fix**: {what was changed}
+- **Files**: {file paths}
+- **Verified**: {yes/no — did re-walk confirm fix?}
+
+---
+
+## Issues Filed
+
+| # | Issue | Severity | Story | Status |
+|---|-------|----------|-------|--------|
+| 1 | [{TITLE}]({ISSUE_URL}) | {severity} | STORY-{ID} | Open |
+| 2 | [{TITLE}]({ISSUE_URL}) | {severity} | STORY-{ID} | Open |
+
+## UX Audit Summary
+
+### Common Patterns
+
+{Identify recurring themes across all walked stories. Examples:}
+
+- **Pattern**: {description of pattern seen across multiple stories}
+  - Affected stories: STORY-{X}, STORY-{Y}, STORY-{Z}
+  - Root cause: {likely root cause}
+  - Recommendation: {what to do about it}
+
+### Systemic Issues
+
+{Issues that aren't tied to one story but affect the whole app:}
+
+1. **{Issue title}**: {description}. Affects {N} stories.
+2. **{Issue title}**: {description}. Affects {N} stories.
+
+## Top 5 Recommendations
+
+{Ordered by impact — what would improve the most stories:}
+
+1. **{Recommendation}** — Would improve {N} stories. {1-2 sentence explanation.}
+2. **{Recommendation}** — Would improve {N} stories. {1-2 sentence explanation.}
+3. **{Recommendation}** — Would improve {N} stories. {1-2 sentence explanation.}
+4. **{Recommendation}** — Would improve {N} stories. {1-2 sentence explanation.}
+5. **{Recommendation}** — Would improve {N} stories. {1-2 sentence explanation.}
+
+## Still Failing
+
+{Stories that failed this run and were not fixed:}
+
+| Story | Failure Point | Reason | Blocked By |
+|-------|---------------|--------|------------|
+| STORY-{ID} | Step {N} | {reason} | {issue link or "not filed"} |
+
+## Story Results Detail
+
+{Compact table of all walked stories:}
+
+| Story | Status | Findings | Fixed | Issues | Notes |
+|-------|--------|----------|-------|--------|-------|
+| STORY-{001} | Pass | 0 | — | — | Clean walk |
+| STORY-{002} | Pass | 2 | 2 | 0 | Fixed: spacing, typo |
+| STORY-{003} | Fail | 3 | 1 | 2 | Blocked on nav redesign |
+
+## Run History
+
+| Run | Date | Walked | Passed | Failed | Fixes | Issues |
+|-----|------|--------|--------|--------|-------|--------|
+| {N} | {DATE} | {N} | {N} | {N} | {N} | {N} |
+| {N-1} | {DATE} | {N} | {N} | {N} | {N} | {N} |
+
+---
+
+*Generated by ux-walker — {ISO_TIMESTAMP}*
+```
+
+## Instructions for the report step
+
+When generating the report from this template, read one file at a time and keep only counts and one-line notes in context:
+
+1. **Read all walk reports**: `docs/ux-walker/stories/STORY-*/walk-report.md`
+2. **Read all findings**: `docs/ux-walker/stories/STORY-*/findings.json`
+3. **Read fix reports**: `docs/ux-walker/fixes/*.md`
+4. **Read issues-filed.md**: `docs/ux-walker/issues-filed.md`
+5. **Read run-history.json**: `docs/ux-walker/run-history.json`
+6. **Aggregate** findings by severity and category
+7. **Identify patterns** — look for the same rubric criterion failing across multiple stories
+8. **Rank recommendations** by how many stories they would improve
+9. **Write** the filled template to `docs/ux-walker/latest-report.md`
+10. **Update run-history.json** with this run's summary