Workflows in Action

The one line: run a ticket as two prompts — one that only researches and writes a plan you review, one that executes it — then read the diff yourself, because the workflow's summary is not the change.

The ticket

A design system with four button sizes, one of them dead. The job: collapse to three, shift every call site across a public marketing site and a logged-in platform, change nothing on screen. Too big to hand-edit, and the failure mode is silent: buttons that never set a size inherit the new default and no type checker notices.

Prompt one buys the plan, not the code

The first prompt touches no source files. It reads the repo and writes a document.

ultracode: run a workflow that gathers all the context on what we should do
here, and draft me a plan document for how we handle this ticket.

That is the whole prompt. The workflow fans out across the component, the call sites, the siblings and the visual regression setup, then converges on a verify stage and a synthesise-and-decide stage, and drops a markdown plan in docs/plans/.

What comes back has a fixed shape, and each part earns its place:

• A verdict. Take the shift. Old sm becomes the new default, old default becomes lg, old lg becomes xl. Class strings move byte-identical, so zero visual change.
• The thing you lose. The small size goes and cannot come back: on mobile the button height is pinned to match input height, and the mobile input has a floor of its own so iOS Safari does not zoom the viewport on focus.
• Collision check. xl already exists and has zero call sites, so the rename is safe.
• The silent break. Roughly 55 buttons carry no size prop. They shift the moment the default moves, and the type checker cannot see it.
• Scope and staging. One PR, three commits, each named.
• Risks and open questions, each with a recommended default.

That last line is the design decision worth stealing. Every open question ships with a recommendation, so answering nothing still produces a sane change. Drop the small size entirely or preserve it — recommend drop. Pin the 55 unsized buttons to their current size or let them grow — recommend pin.

Reviewing the plan is where the leverage is

Ten minutes here is worth an hour later. I accept most of the recommendations as written, which is the point of writing them as recommendations. I reject exactly one: the plan proposes deleting the pagination component because it is unused, and it stays, because it will be needed. On the two sizing questions I take the recommendation as written, because I agree with it: drop the small size, pin the unsized buttons.

You are not reviewing code here. You are reviewing scope and invariants, which are cheap to change in a markdown file and expensive to change in a merged branch.

Prompt two is the execution brief

The second prompt is dictated, not typed — see Voice Dictation — because it is long and specific, and length is the point:

Launch the workflow that does this shift. Fully preserve styling. If something
can run as a script, run it as a script to preserve tokens; otherwise use
workflows and parallel agents, and use cheaper models for the obvious work.
On the sizing questions: go with the recommended answers. On pagination: do
not delete it, it may be used later. As part of verification, build, start the
server, and use the agent-browser CLI to navigate the site and take before and
after screenshots on the important pages, especially public ones. Test user
credentials are in `.env.local` — log into the platform and check there too.
End with a pull request.

Scripts over model edits keeps 55 mechanical renames out of the context window. Browser verification turns "should be identical" into a screenshot pair, and the credentials are what let the agent see the logged-in half of the app at all.

What the workflow actually ran

The workflow script is written under your session directory in ~/.claude/projects/, and saving it from /workflows puts it in .claude/workflows/. It runs in phases you can inspect afterwards: prep, baseline visual snapshot, apply, verify, repair, PR draft.

Apply is the interesting one. The model did not edit 55 call sites. It wrote a code-mod script and ran it, so the model produced one file and the script produced the diff. Delete those code-mod scripts from the branch before you merge: they did their job in one run and are noise in the repo. Verify ran static gates plus visual diffs against the baseline. Repair existed and was skipped, because nothing failed. The PR went through my pr-issue skill, so it came out in the house problem/solution format instead of a list of commits.

You still read the diff

This is the part that is not optional.

Read the diff by route group and check an invariant, not a vibe. Platform pages used the small size, so every platform file should show size="sm" being removed. Static and marketing pages used the default, so they should show lg being added. Shared UI follows: alert dialog cancel and calendar both go large. Any file that breaks the pattern is the one to open.

Then run it. pnpm install, then the dev server, which failed on a port left in use by an earlier agent run and needed the stale process killed. Then an internal server error that looked like a parse error the linter picked up. Both are normal — budget for them instead of reading them as the workflow having gone wrong.

Then click. Public pages first, then log in and walk the platform: catalog, forms, onboarding, calendar, phone input. Most of it looked identical, which is the expected result. One thing did not: ghost buttons on the calendar look wrong at the new size. That is a genuine cosmetic regression, and it becomes a separate issue rather than scope creep in this PR.

If a region of the diff makes you uneasy, do not squint at it. Fire a second workflow scoped to just that region: check the diff for this route group, verify every changed call site there. A scoped review workflow is minutes, and it is the cheapest way to convert unease into a yes or no.

The deviation

The workflow made one deviation from the brief, on an input-group button that sized itself mid-range instead of following the rename, and it was right to. A workflow that follows instructions exactly is one you could trust from the summary. A workflow good enough to correctly disobey you is one you have to read.

What to do

• Split every non-trivial ticket into a research prompt and an execution prompt; never let the first one edit code.
• Require the plan document to carry a verdict, scope, staged commits, risks and open questions with recommended defaults.
• Spend real time reviewing the plan, and answer only the questions where a wrong default would be visible.
• In the execution brief, demand scripts over model edits, cheaper models for mechanical work, browser verification with before/after screenshots, and a PR at the end.
• Review the diff by route group against a stated invariant, and spot-check the result in a browser you drive yourself.
• Scope a second workflow at any region of the diff you are unsure about, and split genuine regressions into their own issue.