How to write visual feedback a coding agent can act on

1. Anchor the comment to the running product

“Make this cleaner” leaves the implementer to guess both the problem and the solution. Start by selecting the element or describing its location precisely. Include the route, screen size, and application state, such as an empty account or a form with a validation error.

A screenshot preserves appearance, while an element reference helps the agent locate the implementation. Neither proves the underlying cause. Describe what you observed without claiming a CSS or component diagnosis unless you have checked it.

2. State what should change and what should stay

Explain the effect on a person using the screen. “The save action disappears below the fold when validation messages appear” is more useful than “the spacing feels wrong.” Then define a result the reviewer can observe.

Bound the task by naming any behavior, content, or adjacent screens that must remain intact. If a design-system rule already resolves the issue, reference that rule instead of proposing a new visual treatment. Separate unrelated issues so each change can be approved or rejected on its own.

Target: [route, element, viewport, and state]
Observed: [what happens now and why it causes a problem]
Desired: [the visible or behavioral result]
Reuse: [existing component, token, or approved reference]
Preserve: [behavior, content, and scope boundaries]
Verify: [steps and expected outcome]

3. Turn one observation into an actionable task

Suppose a founder is reviewing an account settings page on a phone. An email address pushes the save button outside the panel. A focused comment captures the situation without asking for a broader redesign.

Target: /settings/profile, account panel, 390px wide.
Observed: a long email address causes horizontal scrolling.
Desired: the email stays readable and Save remains inside the panel.
Reuse: the existing form layout and spacing tokens.
Preserve: field labels, validation, and save behavior.
Verify: use a long email at 390px and 1280px; confirm no horizontal
scroll and complete a save using the keyboard.

4. Review the feedback before handing it off

Check that the request is still relevant and the desired outcome is clear. Decide which comments should be implemented. In CRRT, accepted visual feedback can be handed to a coding agent with its available context. Follow the agent handoff documentation for the connection and permission details.

Ask the agent to explain its changes and report what it verified. Review the result in the same state and viewport as the original issue. Expand the review to nearby states if the fix touches a shared component. A completion message is a request for review; a person still decides whether the change should merge.

• Confirm the target and issue are reproducible.
• Remove duplicate or conflicting requests.
• Use one observable acceptance check per intended outcome.
• Reopen the original screen and verify the fix before merging.

Common questions