agent-guide: require measuring grid-anchored sixels, not eyeballing#85
Merged
Conversation
Agents recurrently verify the wrong invariant for sixel recordings: they confirm the sixel appears, or that agg rendered it faithfully at the requested cursor cell, and stop there. That misses size/position errors — notably the ~4% undersize from the advertised cell resolution not matching agg's rendered font cell (#84). A 4% gap is invisible by sight. - Corrects the "Sixel graphics in GIFs" bullet, which inaccurately claimed apps "size their raster to match agg's cells" — that mismatch is exactly #84 — and adds it as a caveat. - Adds a "Verifying grid-anchored sixels — measure, don't eyeball" bullet with the cell-calibration recipe: measure agg's real cell from a known grid reference, read the app's raster size from the DCS header, reconcile, and confirm the rendered bbox spans the intended cells. Regenerated cmd/tuirec/agent-guide.md via go generate (verbatim sync). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the doc gap behind #84: agents (and humans) recurrently verify the wrong invariant when checking sixel recordings. They confirm the sixel appears in the GIF, or that
aggrendered it faithfully at the requested cursor cell, and call it done — which misses size/position errors. The headline example is the ~4% undersize from the advertised cell resolution not matchingagg's rendered font cell (#84); a 4% gap is invisible to the eye but trivial to measure.This edits the source
agent/RECORDING-AGENT.md(and regenerates the embeddedcmd/tuirec/agent-guide.mdviago generate):agg's cells" — but that match is exactly what Advertised sixel cell resolution doesn't match agg's rendered font cell — sixels render ~4% undersized #84 shows is broken. Reworded, and the mismatch is now listed as a caveat with a pointer to verify by measurement.agg's real cell from a known grid reference (cellPx = spanPx / cells; notimageWidth / cols—aggadds margins), read the app's raster size from the DCS header (P…q"a;b;W;H), reconcile, and confirm the rendered bbox spans the intended cells.Why
Found while building an agent verification loop for Terminal.Gui (gui-cs/Terminal.Gui PR #5482, #5478). I made this exact mistake: verified
aggwas pixel-faithful to the requested cell and declared success, but never checked the raster size against the layout target — so a sixel that rendered ~1.7 cols short of a dialog border slipped through until caught by eye. The fix is to make the guide demand a measurement for anything grid-anchored. The same recipe is now in the downstream Terminal.Gui guide (Scripts/tuirec/README.md).Verification
go generate ./cmd/tuirec/— embedded copy regenerated; source and embed are byte-identical.go build ./...— passes.🤖 Generated with Claude Code