hernandor/discuss
ADR-driven development, agent spec conventions, decision grilling, English-only artifacts, controlled-language rewrites, 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 English text must be parsed without a human to resolve ambiguity — tool descriptions, error messages, inter-agent instructions, system prompts, status reports — and misreading has a real cost, or when text reads as dense, hedged, or easy to misparse. Triggers: disambiguate, STE100 rewrite, apply Simplified Technical English, plain-language rewrite, controlled-language rewrite, rewrite so an agent cannot misread this. Not for creative or marketing copy.
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.