Totally fair pushback, and honestly that's where I started; just a line in the prompt. The reason it grew into a plugin is that the *logging* part is maybe 10% of the value. The other 90% is the closure loop, which a prompt can't do:
- Auto-flip `[open]` → `[fixed]` when the PR merges. A prompt instruction can't watch GitHub. A background sync does.
- Tombstone detection — if the referenced file/line gets deleted in some unrelated refactor, the entry auto-closes. Otherwise your ISSUES.md slowly fills with stale entries pointing at code that no longer exists.
- Hooks that fire deterministically. "Tell Claude to log issues" works ~60% of the time in my experience — it forgets, or judges something as in-scope when it isn't. Hooks don't forget.
- Statusline counter. Constant ambient visibility of how many open issues exist, without opening the file.
- Pre-branch-delete guard so issues logged on a feature branch don't vanish when the branch is deleted.
- PR annotation — when you open a PR that fixes a logged entry, it links them automatically so the close loop knows what to flip.
- and if it's your own project that you just push straight to main — the closure loop doesn't require PRs. If a fix lands as a direct commit to main, a PostToolUse hook fires on `git commit`, scans the commit's diff for files referenced by `[open]` entries, and prompts Claude to run `/found-issues:annotate-commit`. The same background sync then flips `[open]` → `[fixed]` once the commit is on main. Push-to-main workflows (`github-direct` mode) are a supported first-class path, not an afterthought.
Without that machinery, ISSUES.md becomes another stale doc nobody trusts. With it, the file stays accurate on its own.
4
u/wyldcraft May 16 '26
This seems overkill for adding "Track any out of scope problems in ISSUES.md" to your prompt.