managing-diffmap-repo
Managing the diffmap repo
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.