Write for the person reading diffmaps
People read rendered diffmaps. Their agents write the Markdown, so the people who file issues and read PRs never see fence syntax, parser rules, or CLI output fields. Describe each change as they meet it:
- What they see in the viewer: a card, a panel, a message, a screenshot.
- What their agent now does, or is told: "your agent has to account for every file in a commit's summary, and diffmap warns it at startup when one is missing."
Leave out fence syntax, flags, field names, and source files. The diff, README, and generate-diffmap skill carry those for agents. This applies to everything user-facing: PR titles and descriptions, issue replies, and release notes.
For example, the reply that closed #34, about changed files missing from a spec, should have read:
Thanks for the detailed report. The 24-file example made the gap easy to see. Starting in 0.9.0, your agent has to account for every file a commit changed in that phase's summary card: each one is either a file to review or one it marks as safe to skip. If it leaves a file out, diffmap warns it when the spec opens, so a change like your analytics event can't slip by unmentioned. Files it skips still fold away in the card, and a commit with nothing to review says "No file changes marked as important".
It should not have shown a changes fence with an ignore: line or the warnings output of serve.
Pull requests
-
Branch from
main. Commit the change, then bump the version in its own commit asAGENTS.mddescribes under Releasing (minor for new behavior, patch for fixes). -
For anything a reader sees, capture the rendered diffmap. Serve a small spec that shows each affected state, then take element screenshots with
agent-browser screenshot '<selector>' <path>at 2x scale. -
Host the screenshots on the orphan
pr-assetsbranch under<issue or PR number>/. The bot token cannot create gists, and the images must not land onmain. Add them in a worktree checked out onpr-assets, push, and embed each image by its pinned commit URL, so later pushes never change it:<img src="https://raw.githubusercontent.com/tanishqkancharla/diffmap/<pr-assets sha>/<n>/<file>.png" width="712" alt="What the image shows" />Never delete
pr-assets; merged PRs embed images from it. -
Write the description for the person reading diffmaps, as above: what changes for them, then screenshots, then the version it ships in. Put
Closes #<n>on the first line. -
Merge with
gh pr merge <n> --rebase --delete-branchso the release commit stays separate onmain. Vercel is the check that matters; Cursor Bugbot is optional and often slow.
Issue replies
Thank the reporter for something specific in the report. Say what changed for them and the version it ships in. A merged version bump is staged on npm, not live, until a maintainer approves it, so write "will be in 0.9.0", not "is out in 0.9.0". Don't mention parts of the issue this release doesn't address.