hernandor/discuss
ADR-driven development, agent spec conventions, decision grilling, English-only artifacts, and diff explanations
Use when capturing design discussion that should survive across sessions and contributors (RFC), or when recording/updating the settled design intent a project commits to (ADR). Triggers whenever a design direction is being debated, an architectural choice gets made, an existing decision needs revising, or someone asks "why is it built this way?" or "what is this supposed to do?". Covers the RFC→ADR record lifecycle, not the per-session implementation plan that executes a decision.
Use when adding a project-level rule that AI coding agents should follow (no-print, no-inline-paths, naming conventions, commit format, etc.) and the rule must be discoverable by any harness — Claude Code, Codex, Cursor, Kiro — not pinned to a single editor's hook system.
Use when a plan, feature, design, or implementation direction has unresolved questions, hidden assumptions, or branching decisions that can change the work.
Use whenever writing something that persists — docs, RFCs, ADRs, plans, specs, code comments, docstrings, identifiers, log and error strings, commit subjects, PR and issue text. Load it especially when the conversation is being held in Chinese or another non-English language, when the user asks for the discussion in that language, or when a Chinese/localized document is requested. Prevents the interaction language from leaking into durable artifacts.
Use when asked to explain a code change, diff, commit range, branch, or PR to a human reader as a rich, self-contained HTML page with diagrams and an interactive quiz. Trigger on "explain this diff/PR/branch", "write up this change", "onboarding doc for this change", or a request for a shareable single-file explanation. Not for writing commit messages, PR descriptions, changelogs, or release notes, and not for reviewing a change for defects.
Use when asked to explain a code change, diff, commit range, branch, or PR to a human reader as a MyST Markdown document with mermaid diagrams, callouts, and a dropdown-based quiz. Trigger on "explain this diff/PR/branch", "write up this change", "onboarding doc for this change", or a request for a rendered/publishable Markdown explanation. Not for writing commit messages, PR descriptions, changelogs, or release notes, and not for reviewing a change for defects.