Writing & Maintaining Issues

How we write GitHub issues at Recoup. The bar: a teammate (or a cold agent) can read the issue and know exactly what's done, what's left, why each decision was made, and how to verify any claim — without re-deriving it from git history. Issues are persistent memory, not a TODO dump.

Most substantial work gets a tracking issue: a long-lived issue that coordinates a multi-PR (often multi-submodule) effort. The two reference issues this skill is built from are chat#1747 (cutover plan) and chat#1767 (post-cutover cleanup). Read them if you want the gold standard.

Issues live in a repository

File every issue in recoupable/chat, even when the code lands in api, database, or docs — one home repo means one place to find open work. Never pick the repo by "where the diff lands"; link out to sibling-repo PRs/files by full ref instead (the chat cutover tracker lives in chat though most commits were in api). Wrong repo? gh issue transfer <n> recoupable/chat --repo <wrong-repo> preserves body/comments and leaves a redirect.

Anatomy of a tracking issue

Use these sections in this order. Drop sections that don't apply; never reorder the ones you keep.