post-github-comment

name	post-github-comment
description	Post analysis comments on GitHub issues with AI attribution, appropriate labels, and a non-developer-friendly structure

GitHub Issue Comment Creator

Post concise analysis comments on GitHub issues — for bug investigation, question responses, and technical explanations.

When to Use

Use this skill when the user asks to:

• Comment on a GitHub issue with findings
• Respond to a question on a GitHub issue
• Post investigation results to a GitHub issue

Workflow

1. Fetch the issue — Use gh issue view <number> --repo <owner>/<repo>

2. Understand the issue — Read the title, description, and existing comments

3. Check and assign labels — Review current labels on the issue. If missing or incorrect, assign the correct label(s) based on the issue content (see Label Reference below). Include the label change in the draft shown to the user.

4. Investigate — Search code, read files, query database, compare with original source as needed

5. Draft the comment — Write the full comment text. If labels will be added/changed, note this alongside the draft.

6. Post the comment and update labels — Post via gh issue comment and apply labels via gh issue edit.

7. Edit existing comments — When updating a previously posted comment, ALWAYS use gh api -X PATCH to edit in place. NEVER delete and re-create comments. Before editing, verify BOTH guards below — if either fails, do NOT edit; post a new comment instead.

   1. Author guard — Fetch the comment's author (.user.login) and confirm it matches the currently authenticated account (gh api user --jq .login). NEVER edit a comment created by a different user — only edit comments you (the authenticated account) authored.
   2. AI-attribution guard — Confirm the comment body contains the 🤖 Comment generated by AI footer. NEVER edit a human-written comment, even one authored by the same account.

Label Reference

Always check existing labels on the issue before assigning. Use gh issue view <number> --repo <owner>/<repo> to see current labels, and gh label list --repo <owner>/<repo> --limit 50 to discover the full label vocabulary the project uses.

Below is a common label taxonomy — adapt to whatever conventions the target repo already has. If the repo uses different label names, prefer those.

Type Labels (assign exactly one)

Label	When to Use
type: Bug	Something isn't working — errors, crashes, incorrect behavior
type: Enhancement	New feature or improvement request
type: Documentation	Improvements or additions to documentation
type: Question	Further information is requested
type: Help Wanted	Extra attention is needed

Area / Component Labels (optional)

Many projects scope issues to a specific area (e.g. api: <name>, module: <name>, component: <name>, area: <name>). If the project uses such labels, assign one when the issue is clearly scoped to that area.

Status Labels (assign when closing or triaging)

Label	When to Use
status: Analyzed	AI agent has analyzed the issue and posted a comment — always add this when posting a comment
status: Spec Conflict	Analysis found that a specification/design document conflicts with the actual source code — always add this when the issue references a spec but the original code behaves differently
status: Duplicate	Issue is a duplicate of another
status: Invalid	Issue is not valid or not reproducible
status: Wontfix	Issue will not be worked on

Label Assignment Rules

1. Every issue should have a type label — if missing, determine from content and assign
2. ALWAYS add status: Analyzed (or the project's equivalent) — whenever posting a comment via this skill, add a label indicating the issue has been analyzed by AI
3. ALWAYS add status: Spec Conflict (or equivalent) — when the analysis finds that a spec/design document conflicts with the original source code (source code is the top-level source of truth)
4. Area labels are optional — only add if the issue clearly relates to a specific area
5. Other status labels — only add when resolving/closing an issue
6. Do not remove existing correct labels — only add missing ones or replace incorrect ones

If the repo has no labels defined yet, skip the label steps or ask the user whether to create a baseline.

Format Rules

• Language: Match the language used in the issue thread, or whatever language the project/team prefers. Keep technical terms like table names, field names, and API paths in English even when writing in another language.
• Non-developer-friendly: Comments may be read by business analysts, product managers, or other non-developers. If technical terms are used, always include a glossary section (as a blockquote at the top). Explain what values mean in business context, not just what they are technically — e.g., write "has been finalized (stored)" instead of "STR found in storage"; write "this document set has already been scanned in" instead of "parent != null".
• Markdown allowed: Use ##, ###, bullet points, inline code — GitHub renders markdown
• Length: Concise — focus on answering the question or explaining the finding
• Structure: Lead with glossary (if technical terms used), then finding/answer, then supporting details
• No filler: Skip greetings, signatures, timestamps — GitHub adds those automatically
• AI attribution: Always end the comment with the footer below (outside any section)
• Edit over delete: When updating an existing comment, use gh api -X PATCH to edit instead of deleting and re-creating
• Never edit another user's comment: Only edit comments authored by the currently authenticated account AND carrying the AI footer — verify both before any PATCH (see Workflow step 7)

AI Attribution Footer

Always append this at the very end of every comment:

---
🤖 Comment generated by AI (Claude <MODEL_NAME>)

Replace <MODEL_NAME> with the actual model name being used (e.g., Opus 4.6, Sonnet 4.6).

Comment Template

> **Glossary:** (include when comment uses technical terms — translate the label into the comment's language)
> - **{term}:** {plain-language explanation}
> - **{term}:** {plain-language explanation}

## Analysis

{Main finding or answer — 1-3 sentences with relevant file/table/field names}

### Detail (if needed)

- {Supporting point 1}
- {Supporting point 2}

{Optional: recommendation or next steps}

---
🤖 Comment generated by AI (Claude <MODEL_NAME>)

Examples

Answering a Question

## Analysis

Checked the original source code — the current logic matches the original. There is no site-existence validation before upload.

### Details

- The original upload service passes `siteid` straight through to the storage layer without checking
- The missing `/` is caused by path-resolution collapsing a double slash, not by API-side sanitization

---
🤖 Comment generated by AI (Claude Opus 4.6)

Bug Analysis

## Analysis

Cause: `UserGroupService.java` only checks group prefixes `_A / _B / _C` and is missing `_D_`, producing `category=X` instead of `category=Y`.

### Fix

Add a `_D_` check in `UserGroupService.java` after the `_A / _B / _C` block.

---
🤖 Comment generated by AI (Claude Sonnet 4.6)

Commands

# View issue (includes current labels)
gh issue view <number> --repo <owner>/<repo>

# View existing comments
gh issue view <number> --repo <owner>/<repo> --comments

# List all available labels
gh label list --repo <owner>/<repo> --limit 50

# Post new comment
gh issue comment <number> --repo <owner>/<repo> --body "$(cat <<'EOF'
<comment content>
EOF
)"

# Get comment ID of the last comment on an issue
gh api repos/<owner>/<repo>/issues/<number>/comments --jq '.[-1].id'

# --- Before editing, verify BOTH guards ---

# Who am I? (the currently authenticated account)
gh api user --jq .login

# Guard 1 — author: fetch the comment's author; must equal the account above
gh api repos/<owner>/<repo>/issues/comments/<comment-id> --jq .user.login

# Guard 2 — AI footer: body must contain the AI-attribution footer
gh api repos/<owner>/<repo>/issues/comments/<comment-id> --jq '.body | contains("🤖 Comment generated by AI")'

# Edit existing comment — ONLY after both guards pass (NEVER delete + create)
gh api -X PATCH repos/<owner>/<repo>/issues/comments/<comment-id> -f body="$(cat <<'EOF'
<updated content>
EOF
)"

# Add labels to issue
gh issue edit <number> --repo <owner>/<repo> --add-label "type: Bug"
gh issue edit <number> --repo <owner>/<repo> --add-label "type: Bug,area: api"

# Remove a label from issue
gh issue edit <number> --repo <owner>/<repo> --remove-label "type: Question"