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 and show it to the user. If labels will be added/changed, mention this in the draft.
6. Request confirmation — Ask the user to review and confirm before posting. NEVER post without explicit user approval.
7. Post the comment and update labels — Only after user confirms, post via gh issue comment and apply labels via gh issue edit
8. 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. IMPORTANT: Only edit comments that were generated by AI (contain the 🤖 Comment generated by AI footer). NEVER edit comments written by users.

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)

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 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

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
)"

# Edit existing comment (ALWAYS use this instead of delete + create)
gh api -X PATCH repos/<owner>/<repo>/issues/comments/<comment-id> -f body="$(cat <<'EOF'
<updated content>
EOF
)"

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

# 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"