/share-fix

name: share-fix
description: After shipping a non-trivial fix, find related GitHub issues across the ecosystem, draft helpful human-sounding comments linking the fix and root cause, and optionally file upstream issues. Drafts must pass as human writing or the user's GitHub reputation suffers. Works on the current session's fix or retroactively on past commits/PRs. Always asks for approval before posting anything public.
argument-hint: "[optional: commit SHA, PR number, or description of the fix]"

Share Fix Agent

Target: $ARGUMENTS

After fixing a non-trivial bug, especially one rooted in a third-party library or package, find other people hitting the same issue across GitHub and leave helpful comments pointing to the fix. The goal is to be a good open-source neighbor: save other developers hours of debugging by making findings searchable.

Use this skill whenever a merged fix works around or documents an upstream bug that other downstream projects likely hit or will hit. Typical triggers: a library minification bug, a terminal emulator quirk, a polyfill issue, a protocol-level misbehavior, a platform-specific gotcha.

Voice Calibration (Always Run First)

**Critical:** GitHub culture is allergic to AI-written content. If a comment drafted for the user is detected as AI, the user's reputation takes real damage. Drafts must pass as human on first read. This is not optional.

Before drafting anything, load voice context:

1. **Read memory files.** Check `~/.claude/projects/*/memory/` for files like `feedback_comment_style.md`, `feedback_no_em_dashes.md`, `user_*.md`. Read the bodies, not just the MEMORY.md index. These carry the user's voice rules, honest project positioning, and hard writing constraints (em dashes, "we" vs "i", etc). 2. **Sample recent comments from the user in the target repo.** For each target repo:

   gh search issues --commenter <user> --repo <owner>/<name> --limit 10 --include-prs
   gh api repos/<owner>/<name>/issues/<n>/comments --jq '.[] | select(.user.login == "<user>") | .body'

Read a couple of the user's actual comments. Mimic their length, lowercase pattern, shorthand, and emotional register. 3. **Only then start Step 1.** Drafts written from a default corporate register and casualized afterwards always read as "AI trying to sound casual". Start in the right register.

Step 1: Understand the Fix

Before searching the ecosystem, understand what the fix actually does:

• Read the commit diff, PR description, and any referenced issue body
• Identify the **root cause** (not just the symptom): what third-party behavior or bug is being worked around?
• Identify the **upstream package** and version involved
• Identify the **downstream symptom**: what did end users actually see?
• Identify the **workaround mechanism**: what change makes the symptom go away?

If any of these are unclear from the commit or PR alone, read the relevant source files, including the published `node_modules` source for the upstream package, before proceeding. Do not start drafting comments until you can explain all four in plain language. Guessed root causes damage the user's credibility when they turn out wrong.

Step 2: Research Outreach Targets

Dispatch a `researcher` subagent. The research is wide-ranging and benefits from parallel searching across many repos. Brief it on:

• The root cause in technical terms
• The symptoms users would describe in layperson terms
• The upstream package and version
• Example search vocabulary both technical users and lay users might use
• The honest, non-marketing framing for the user's project (pulled from memory)

Ask it to return, ranked by confidence:

1. **Open or recent issues on the upstream repo** matching the symptom or root cause 2. **Existing issues on downstream projects** that use the same package and might have hit this 3. **High-traffic discussion megathreads** where affected users are gathering (highest-leverage comment targets) 4. **Closed issues** still highly-reacted or searchable, where a comment would help future searchers 5. **The right upstream tracker** to file a new issue if none exists

The researcher should return URLs, issue numbers, match rationale, and confidence ratings. Skip low-confidence targets to avoid spamming. A comment on the wrong issue damages signal for everyone.

**Also check which targets the user has already commented on** via `gh search issues --commenter <user> --repo <owner>/<name>` so the skill does not duplicate outreach.

Step 3: Draft Comments (Always, Not Post Yet)

Draft tone guidance (read this every time):

• **First person singular always.** "i hit this", "i built", "my fix". Never "we" unless the user has explicitly said they're part of a team.
• **Lowercase starts on most sentences in informal comments.** Including the word "i". Some caps are fine, consistent Title Case is not.
• **Shorthand.** `w/` for with, `rn` for right now, `imo`, `afaik`, `tbh`, `btw`, `fwiw`, `repro`, `prod`, `config`, `deps`. Write `xtermjs` not `xterm.js` in prose. `electron`, `vscode` lowercase. Natural, not performative.
• **Short sentences mixed with occasional run-ons.** Don't over-polish. Comma splices are fine. Sentence fragments for emphasis are fine.
• **Drop the link, state what it does, done.** No sign-offs. No "hope this helps". No "let me know if you have questions". The comment ends when the information ends.
• **Honest project positioning.** Load from memory. Describe the user's project factually. Not "small indie wrapper", not "the leading X for Y".
• **Emotional honesty where natural.** "was mad enough to fix it myself", "took me a while to untangle". Don't force it, don't suppress it.
• **No corporate phrasing.** No "I wanted to share", "I hope this is helpful", "happy to provide more context", "looking forward to your thoughts". These are AI tells.
• **No bulleted "key takeaways" in informal comments.** Prose only. Save bullets for upstream issue bodies where st