github-comment-quality

# GitHub Comment & Communication Quality Standards ## Core Philosophy > **GitHub text is technical communication with reviewers and collaborators, not an internal scratchpad, proof-of-work ledger, or bot execution diary.** Write for the human reader: deliver the outcome, essential technical rationale, and verification tersely. Respect reviewer bandwidth by answering the question or fixing the issue with the minimal words needed. ## Authorization & Scope Boundaries - **Drafting vs. posting:** Drafting text does not authorize posting it unless the user explicitly requested the action (e.g. "open a PR", "reply to the review", or "file an issue"). Do not post unprompted comments or create unrequested issues. - **Do not auto-create tangential issues:** When discovering an unrelated bug or CI gap during a task, flag it locally or ask the user whether to file an issue. Never automatically create new issues without user authorization. --- ## The 8 GitHub Communication Anti-Patterns ### 1. The "Development Diary" PR Description - **Anti-Pattern:** Turning the PR body into a narrative journal of everything thought, tried, measured, and discarded (e.g. multi-paragraph design essays, discarded alternatives, benchmark replicas, and obsolete drafting history). - **Rule:** A PR body documents the **current state of the branch**, not the historical drafting journey. Keep it focused: - **Summary:** 1-2 bullet points on the user-visible or architectural change. - **Key Changes:** Concrete implementation details (only if non-obvious). - **Verification:** Specific tests added/passed and manual checks (no raw terminal dumps). - **Fixes:** Issue references. - _(For small, 1-3 line changes, a 1-2 sentence description without section headings is preferred)._ - ❌ _(500-word essay explaining rejected library dependencies, how test harnesses were configured, and pasting 40 lines of terminal output)_ - ✅ ```markdown Fixes #72 ## Summary - Initialize upstream MCP servers concurrently during startup rather than serially. - Bounds startup latency to the slowest single upstream server. ## Changes - Launch each configured upstream in its own goroutine and merge results deterministically by sorted server name. - Retain child process handles to ensure clean process termination on shutdown. ## Verification - Added unit tests for concurrent launch timing and deterministic tool ordering. - Local benchmark: 9 upstreams initialize in 9.7s (down from 31.1s serial). - `go test -race ./...` passes. ``` ### 2. Disproportionate & Compliance-Obsessed Review Replies - **Anti-Pattern:** Responding to a 1-line review comment with a multi-paragraph compliance report detailing every rule followed, repeating diffs, and quoting the prompt. - **Rule (Proportionality):** Deliver the shortest response that conveys the decision-changing facts or applied fix. - **Routine fix:** 1 line + commit SHA. - **Technical constraint / disagreement:** State the concrete invariant, constraint, or test evidence directly without entering into philosophical debates or meta-arguments. - ❌ ```text Ran both humanizer and comment-and-documentation-quality skills on the guide. Flagged bold-spam (§15), announcing the next point (§28), repetition (§11), and stripped em dashes under Anti-Pattern 1 in commit 7dfe483... ``` - ✅ `Updated in 7dfe483. Removed the MCP server comparison and tightened the wording. Build and tests pass.` ### 3. Explaining "Why I Made the Mistake" (Defensive Post-Mortems) - **Anti-Pattern:** Explaining how the model hallucinated, got confused by precedent code, or made an incorrect assumption. - **Rule:** Nobody needs a post-mortem of AI confusion. Report the correction directly. - ❌ ```text The URL split was my mistake. I carried over the Home Assistant case where aiohttp 404s on the slash variant, and assumed the same applied here without checking. Reverted in b64a2fd... ``` - ✅ `Reverted the URL change and restored the test connection step in b64a2fd. The HTTP endpoint on 27123 remains the default.` ### 4. Emotional & Meta-Commentary (Self-Evaluation) - **Anti-Pattern:** Self-evaluating performance or narrating intent: - _"Fair hit on all three."_ - _"I can name how it got there."_ - _"That is not a bot failing to converge."_ - _"Deliberately minimal..."_ - **Rule:** Delete performative self-evaluation, defensive remarks, and emotional framing. Keep comments technical, neutral, and direct. (Brief professional courtesy when acknowledging a mistake is acceptable). - ❌ `Fair hit on all three. You are right that I argued the point instead of doing it, and that citing other guides was the wrong move.` - ✅ `Updated in 74f9283. Removed all em dashes across the guides and tightened the setup instructions.` ### 5. Bot Signatures, Watermarks & Generated-By Footers - **Anti-Pattern:** Appending `_Generated by Claude Code_`, `_Reviewed by OpenAI Codex_`, or model watermarks. - **Rule:** Never include voluntary "Generated by", "Automated by", or tool attribution footers in PRs, issues, or comments. - ❌ `Fixed the typo in 3a1b2c3.\n\n---\n_Generated by Claude Code_` - ✅ `Fixed the typo in 3a1b2c3.` ### 6. Standalone Verification Noise - **Anti-Pattern:** Leaving comments on public issues or PRs that only narrate local session activity without advancing the review (e.g. dumping raw `go test` output or announcing that a local check ran when no action is needed). - **Rule:** Include verification summaries inside the PR body or review response. Do not post standalone execution transcripts. - ❌ ```text I merged this branch onto main in a throwaway worktree and verified it locally: $ go test -race ./... ok github.com/dvcrn/mcpnest/internal/app 7.846s ``` - ✅ _(Include in PR body or relevant review response instead: `Verified locally with go test -race ./...`)_ ### 7. Tangential Findings & Scope Creep - **Anti-Pattern:** Appending unrelated bugs, CI failures, or observations found in other parts of the repo into a specific PR or review thread. - **Rule:** Keep every PR and review thread scoped strictly to its own subject. Flag tangential issues locally or ask the user before filing a separate issue. - ❌ `Fixed the query parameter in 4b5c6d7. Also noticed that GitHub Actions CI configuration in .github/workflows/ci.yml is missing a Go cache step, which might slow down builds.` - ✅ `Fixed the query parameter in 4b5c6d7. Tests pass.` ### 8. Describing What You Deliberately Did Not Do - **Anti-Pattern:** Listing hypothetical tasks that were not done (_"One thing I did not do...", "I did not touch older files...", "I left that open..."_). - **Rule:** Only mention an omission if it represents a genuine pending decision or known limitation the reviewer must evaluate. - ❌ `I did not touch the older guides beyond the dashes because antigravity-sync-macos is 162 words and reads thin.` - ✅ _(Preserving a real technical limitation)_ `This change kills direct child processes on cancellation. Process-group cleanup for grandchildren is not yet handled and should be addressed in a follow-up.` --- ## Technical Precision & Factual Accuracy 1. **Never fabricate claims or evidence:** Do not invent test passes, benchmarks, commits, issue numbers, or verification steps. Do not claim a fix was applied unless it was committed and pushed. 2. **Preserve technical uncertainty:** Do not turn `may` into `will`, `typically` into `always`, or an experimental observation into a universal guarantee. 3. **Give each fact one home:** Do not duplicate the same investigation across the PR body, review thread, status comment, and final summary. 4. **Preserve technical jargon:** Use precise technical vocabulary (e.g. _race condition, mutex contention, atomic swap, WAL mode_); do not over-explain basic language semantics. --- ## Formatting, Punctuation & Tone Rules 1. **Zero em dashes (`—`), en dashes (`–`), and pause double-hyphens (`--`):** Use colons, parentheses, or separate sentences. (Preserve literal CLI flags such as `--verbose`). 2. **No bold-spam or decorative emojis:** Avoid bolding every second phrase or prefixing headings with `🚀`, `💡`, `✅`. 3. **No raw terminal dump logs:** Summarize test and benchmark results cleanly in a single line or concise table, rather than dumping 40 lines of test output. 4. **No throat-clearing / sycophancy:** Cut _"Great suggestion!", "You're absolutely right!", "Let's dive in"_. 5. **Use clean titles:** Keep PR and issue titles specific, concise, and free of conversational fluff. PR titles should be imperative (e.g. `Fix dirty state warning in AI dialog`). Issue titles should clearly describe the problem or goal (e.g. `AI dialog shows stale warning after save` or `Support concurrent upstream initialization`). Avoid conventional commit prefixes (`feat:`, `fix:`) unless required by the repo. --- ## Templates For artifact-specific examples, read [templates.md](references/templates.md). Choose the template matching a PR description, review comment, or issue; do not impose all sections on a short reply.