gilde

← All craftbooks

Implement a UX Change

Build: interactive and webevalv1.0.2released 2026-09-05

Deliver a described UX change the disciplined way: capture the before state from the real markup, make the smallest coherent change at the real sites in the product's own conventions, and prove the after state with the existing behaviors still working — under an enforced independent review.

Steps

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

  1. Understand and capture the before stateproduct engineerentry

    Restate the change as the user experiences it, find the real surfaces, and quote the current markup and wiring.

    Show working prompt
    The UX change to deliver: {{scope}}

Understand before touching anything. Restate the requested change as the USER would experience it — what they see and do today, what they should see and do afterwards. Then find the involved surfaces in the REAL code: read the actual pages, components, styles, and scripts with `read_file` until you can point at the exact markup and wiring behind the current experience. Capture the BEFORE state from those files — quote the relevant snippets (the current markup, the handler, the shortcut wiring) so the change can later be judged against reality rather than memory. Catalogue every behavior attached to the surfaces you will touch — handlers, keyboard shortcuts, element ids other code references, state — because each of them must still work afterwards. If the request is ambiguous, record the reading you chose and why; if the described surface cannot be located in this codebase at all, say so honestly and stop rather than inventing one.

Write `{{workPath}}/before.md` with exactly these sections: `## Request` (the change in the user's terms), `## Current behavior` (what happens today, with the quoted snippets), `## Surfaces involved` (each file and the part it plays, with backtick paths). Every path you cite must be real.

Observable handoff: write the completed result to `{{workPath}}/before.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  2. Implement the smallest coherent changefrontend engineer

    Deliver the request at the real sites, in the product's own conventions, keeping existing behaviors wired.

    Show working prompt
    Read `{{workPath}}/before.md` and deliver the SMALLEST coherent change at the real sites it names — edit the actual files with `read_file` plus `write_file`/`replace_in_file`; there is no prescribed output path for the change itself. Match the surrounding product's conventions: reuse its spacing, naming, class patterns, and markup style rather than inventing a new one — open neighboring code to see how this product already does the same kind of thing. Keep every existing behavior working: the handlers, keyboard shortcuts, element ids, and state catalogued in before.md must still be wired when you are done — move them with the element rather than dropping or duplicating them. Do not smuggle in unrequested changes; polish beyond the request is scope creep, not generosity.

Then write `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (the request, one paragraph), `## Change` (what you altered and how it delivers the request), `## Files touched` (backtick path per line), `## Consistency notes` (which existing conventions you followed and where you saw them), `## Risk` (what could break; be honest about anything unverified), `## How to verify` (the exact steps a person follows to see the new experience). Before working, open `{{workPath}}/before.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/fix-notes.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  3. Validate the changed flowproduct engineer

    Walk the new experience and build a concrete before/after grounded in the real files.

    Show working prompt
    Prove the change as the user would experience it. Read `{{workPath}}/before.md` and `{{workPath}}/fix-notes.md`, then re-open the changed files with `read_file` and walk the flow: where the element lives now, what happens on each interaction, where focus goes, what each shortcut does. Build a concrete before/after comparison grounded in the real files — quote the after state next to the before state that before.md recorded. Re-check every behavior from before.md's catalogue: each handler, shortcut, and id must be verifiably still wired in the current code. Say plainly which parts you INSPECTED (read the code) versus EXERCISED (actually ran or interacted with) — anything that is neither is unverified and must be named, never claimed.

Write `{{workPath}}/validation.md` with exactly these sections: `## Before / after` (the concrete comparison, quoting both states), `## What was exercised` (inspected versus exercised, honestly), `## Result` (delivered as requested, or what remains open and why). Before working, open `{{workPath}}/before.md`, `{{workPath}}/fix-notes.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/validation.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  4. Evaluate the deliverableux reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `{{workPath}}/validation.md`, `{{workPath}}/before.md`, `{{workPath}}/fix-notes.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.

1. The delivered change matches the request as a user would judge it — open the changed files and walk the flow; do not grade from fix-notes.md alone.
2. The change respects the surrounding product's conventions — open neighboring code and compare naming, spacing, and markup patterns; a one-off new style where an existing pattern served does not pass.
3. Nothing that worked before broke: every handler, keyboard shortcut, and id catalogued in before.md is still wired in the current code — check the wiring, not the claim.
4. before.md quotes the real prior state and validation.md's before/after is grounded in the current files, not reconstructed from memory.
5. The change is minimal: no unrequested alterations rode along with it.

Open `{{workPath}}/validation.md`, `{{workPath}}/before.md`, `{{workPath}}/fix-notes.md` with `read_artifact`. Write the evidence-backed review to `{{workPath}}/review.md` in the artifacts drawer with `write_artifact`.

List the findings as a markdown table with columns `| Severity | File | Line | Problem | Fix |` (severities: critical/major/minor/nit; empty table only on PASS). Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate ENFORCES the verdict: a well-formed REVISE is rejected and routed back to `repair` automatically, carrying your findings — so list every finding in the table with a concrete fix. On PASS, `advance_task_step` to `finish`. Never write PASS while a criterion is unmet.
  5. Finishproject lead

    All deterministic and reviewer criteria passed.

    Show working prompt
    The independent review passed. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/validation.md`, `{{workPath}}/before.md`, `{{workPath}}/fix-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  6. Repair the deliverablefrontend engineer

    Fix only the concrete gaps from the latest independent review.

    Show working prompt
    Read `{{workPath}}/review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/validation.md`, `{{workPath}}/before.md`, `{{workPath}}/fix-notes.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/validation.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
  7. Escalate unresolved concernsproject lead

    The bounded repair loop ended without a defensible pass.

    Show working prompt
    The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license