gilde

← All craftbooks

Codebase UX Review

Review and QAevalv1.0.0released 2026-06-05workflow: build-loop

Review the user experience implemented across a codebase and, when runnable, exercise the key flows in a real browser. Starts from the indexed UI surface rather than one screenshot, traces primary journeys and state transitions, then leaves a prioritized morning report covering information architecture, comprehension, feedback, recovery, consistency, responsive behavior, and user impact with source or runtime evidence. Use for a weekly UX sweep, product usability review, interaction review, or finding the highest-impact friction in an application.

Steps

Entry step: map. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Map the experiencereviewerentry

    inventory surfaces, actors, journeys, states, and review coverage from the index

    Show working prompt
    Call `map_repo`, `list_file_issues`, and targeted `search_code` queries to inventory the implemented experience: routes/views, navigation, dialogs, forms, onboarding, settings, empty/loading/error/success states, destructive actions, and responsive breakpoints. Read product/UX guidance already in the workspace before applying generic taste. Identify primary actors and 3-7 highest-value journeys with their start, goal, and risky transitions. Record which surfaces are runnable and which can only be reviewed statically. Write the surface map, journey matrix, local design principles, index coverage, and test plan to `notes/ux/surface-map.md`. No findings yet.
  2. Exercise and inspect journeysreviewer

    walk key flows and verify indexed leads in source or a browser

    Show working prompt
    Walk every prioritized journey. When the app is runnable, use `run_playwright_script` to test it at representative desktop and mobile sizes while checking navigation, focus, validation, loading, empty, error, success, cancellation, and recovery states. When it is not runnable, trace the relevant route/component/state symbols with `outline_file`, `read_symbol`, and `find_references`; label static inferences honestly. Verify indexed leads rather than repeating them. For each confirmed issue capture journey, step, evidence (screenshot/selector or file:line), expected vs actual experience, affected users, severity, frequency, and a concrete design/change recommendation. Also record strengths and tested-clean states. Write the evidence log to `notes/ux/evidence.md`.
  3. Write the UX reportreviewer

    prioritized, journey-centered usability report for morning triage

    Show working prompt
    Write `ux-review.md` with: `## Verdict`, `## Coverage`, `## Journey scorecard`, `## Findings`, `## Strengths`, `## Not verified`, and `## Morning action list`. Order findings by user harm × frequency, not visual polish. Every finding must cite a journey step and runtime or file:line evidence, explain the user consequence, and give a concrete recommendation with effort. Cover information architecture, comprehension, feedback/state visibility, error prevention/recovery, consistency, and responsive behavior. Keep accessibility defects cross-referenced rather than duplicating the a11y audit. State when a judgment is a static inference. On a loop-back, fix only named gaps.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Grade `ux-review.md`: (1) the important surfaces and journeys are covered; (2) findings cite a journey step plus runtime or real file:line evidence; (3) static inference is distinguished from exercised behavior; (4) loading, empty, error, success, cancellation, and recovery states were considered; (5) severity follows user harm and frequency; (6) recommendations are concrete and effort-aware; (7) strengths, unverified areas, and an actionable morning list are present. PASS all or loop back with exact gaps.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Toolsets

Source

View this craftbook on GitHub · MIT license