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

Every issue belongs to one repo (gh issue create --repo recoupable/<repo>). There is no org-level issue — cross-repo work lives in one "home" repo's tracking issue that links out to PRs/issues in the others.

File every issue in recoupable/chat — even when the actual code lands in api, database, or docs. One home repo means devs have a single place to find open work. Do not pick the repo by "where the diff lands"; link out to sibling-repo PRs/files by full ref instead (e.g. the chat cutover tracker lives in chat even though most commits were in api). If an issue gets opened in the wrong repo, move it: gh issue transfer <n> recoupable/chat --repo <wrong-repo> (preserves body/comments, 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.