gh-issue-triage

--- name: gh-issue-triage description: GitHub issue triage workflow with contributor profile extraction. Analyze → clarify → file cells → tag → implement → credit. Captures Twitter handles for changeset acknowledgments. tags: - github - issues - triage - contributors - twitter - credits --- # GitHub Issue Triage - Analyze → Clarify → File → Tag → Implement → Credit ## Philosophy **Issues are conversations, not tickets.** Treat contributors with respect - they took time to file the issue. Extract their profile info so changesets can properly credit them when fixes ship. - Good issue? **CLARIFY** → file cell → acknowledge → implement → credit in changeset - Bug report? **REPRODUCE** → confirm → file cell → fix → credit - Feature request? **VALIDATE** → check scope → defer or implement → credit - Duplicate? **LINK** → close gently → no cell needed - Not a bug? **EXPLAIN** → close kindly → no cell needed ## The Workflow ``` ┌─────────────────────────────────────────────┐ │ ANALYZE → CLARIFY → FILE → IMPLEMENT │ ├─────────────────────────────────────────────┤ │ │ │ 1. FETCH ISSUE │ │ gh issue view <number> --json ... │ │ → Get title, body, author, state │ │ │ │ 2. GET CONTRIBUTOR PROFILE │ │ gh api users/<login> │ │ → twitter_username, blog, bio, name │ │ → Store in semantic-memory for credits │ │ semantic-memory_store( │ │ information="Contributor @{login}: │ │ {name} (@{twitter} on Twitter). │ │ Filed issue #{number}. Bio: {bio}", │ │ tags="contributor,{login},issue-{#}" │ │ ) │ │ │ │ 3. ANALYZE │ │ → Is it a bug? Feature? Question? │ │ → Can you reproduce? │ │ → Is it in scope? │ │ │ │ 4. CLARIFY (if needed) │ │ → Ask for repro steps │ │ → Request context/versions │ │ → Genuine questions, not interrogation │ │ │ │ 5. FILE CELL │ │ hive_create( │ │ title="Issue #N: <summary>", │ │ type="bug|feature", │ │ description="<link + contributor>" │ │ ) │ │ │ │ 6. TAG ISSUE │ │ gh issue edit <number> --add-label bug │ │ │ │ 7. IMPLEMENT │ │ → Fix the issue │ │ → Write tests │ │ → Close cell │ │ │ │ 8. CREDIT IN CHANGESET │ │ → Add "Thanks @twitter" or │ │ "Thanks <name> (<blog>)" │ │ │ └─────────────────────────────────────────────┘ ``` ## Decision Matrix | Issue Type | Action | Create Cell? | Credit? | |------------|--------|--------------|---------| | Valid bug with repro | Confirm → file cell → fix | ✅ Yes | ✅ Yes | | Bug missing repro | Ask for steps → wait | ⏸️ Defer | ✅ Yes (when fixed) | | Feature request in scope | Validate → file cell → implement | ✅ Yes | ✅ Yes | | Feature out of scope | Explain why → close | ❌ No | ❌ No | | Duplicate | Link to original → close | ❌ No | ✅ Maybe (if original gets fixed) | | Question/support | Answer → close | ❌ No | ❌ No | | Already fixed | Confirm → close | ❌ No | ✅ Yes (if recent) | ## SDK Commands ```bash # Get issue details bun run scripts/issue-summary.ts <owner/repo> <number> # Returns: title, body, author, state, labels, url # Get contributor profile (includes Twitter!) bun run scripts/get-contributor.ts <login> [issue-number] # Example: bun run scripts/get-contributor.ts justBCheung 42 # Returns: # - Profile details (name, twitter_username, blog, bio, avatar_url) # - Ready-to-paste changeset credit: "Thanks to Brian Cheung ([@justBCheung]...)" # - Ready-to-paste semantic-memory_store command ``` ## Quick Triage Pattern ```typescript import { getIssueSummary } from "./scripts/issue-summary.ts"; import { getContributor } from "./scripts/get-contributor.ts"; // 1. Fetch issue const issue = await getIssueSummary("owner/repo", 42); // 2. Get contributor profile const contributor = await getContributor(issue.author.login); // 3. Store contributor in semantic-memory for future credits semantic-memory_store({ information: `Contributor @${contributor.login}: ${contributor.name || contributor.login} ${contributor.twitter_username ? `(@${contributor.twitter_username} on Twitter)` : ''}. Filed issue #42. Bio: '${contributor.bio || 'N/A'}'`, tags: `contributor,${contributor.login},issue-42` }); // 4. Analyze and decide if (issue.body.includes("TypeError") && issue.body.includes("steps to reproduce")) { // Valid bug with repro - file cell await hive_create({ title: `Issue #42: ${issue.title}`, type: "bug", description: `${issue.url}\n\nReported by: ${contributor.name || contributor.login}\nTwitter: ${contributor.twitter_username || 'N/A'}\n\n${issue.body.slice(0, 500)}` }); // Tag issue await $`gh issue edit 42 --add-label bug`; } else if (!issue.body.includes("steps to reproduce")) { // Missing info - ask nicely await $`gh issue comment 42 --body "Hey ${contributor.name || contributor.login}! Could you share steps to reproduce? That'll help me track this down."`; } ``` ## Acknowledgment Comment Templates **After filing cell:** ``` Hey [name]! Thanks for reporting this. I've filed a tracking issue - we'll get this sorted. ``` **After asking for clarification:** ``` Hey [name], could you share [X]? That'll help me nail down what's happening. ``` **After fixing:** ``` Fixed in [commit]! Should be in the next release. Thanks for catching this 🙏 ``` **When closing as duplicate:** ``` This is a dupe of #[N] - tracking there. Thanks for the report! ``` **When closing as not-a-bug:** ``` This is actually expected behavior because [reason]. If you're trying to [X], here's how: [link/example] ``` ## Changeset Credit Templates **With name AND Twitter handle (PREFERRED):** ```markdown --- "package-name": patch --- Fixed [bug description] Thanks to [Name] ([@twitter_username](https://x.com/twitter_username)) for the report! ``` **With Twitter handle only (no name):** ```markdown --- "package-name": patch --- Fixed [bug description] Thanks to [@twitter_username](https://x.com/twitter_username) for the report! ``` **With name only (no Twitter):** ```markdown --- "package-name": patch --- Fixed [bug description] Thanks to [Name] (@github_username on GitHub) for the report! ``` **GitHub username only (no name, no Twitter):** ```markdown --- "package-name": patch --- Fixed [bug description] Thanks to @github_username for the report! ``` **Why include both name and Twitter?** Names are human, Twitter handles enable engagement. "Thanks to Brian Cheung ([@justBCheung](https://x.com/justBCheung))" gives credit AND makes it easy to tag them when tweeting the release. ## Profile Extraction GitHub user profiles have these useful fields: ```json { "login": "bcheung", "name": "Brandon Cheung", "twitter_username": "justBCheung", // ← THIS! "blog": "https://example.com", "bio": "Building cool stuff", "avatar_url": "...", "html_url": "..." } ``` **Always fetch the profile** - it's one API call and gives you credit info for changesets that get tweeted. ## Voice Guide (You're Joel the Maintainer) **DO:** - Be genuine and conversational - Use "Hey [name]" not "Hello" - Say "Thanks for the report!" not "Thank you for your contribution" - Use emoji sparingly (🙏 after fixes, not in every comment) - Explain WHY something is/isn't a bug - Link to docs/examples when helpful **DON'T:** - Corporate speak ("We appreciate your feedback") - Interrogate ("Can you provide more details about...") - Over-promise ("We'll fix this ASAP!") - Apologize excessively ("Sorry for the inconvenience") - Use ticket numbers as if it's Jira ("TKT-1234") **Examples:** ❌ **Corporate:** "Thank you for your contribution. We have logged this issue and will investigate." ✅ **Joel:** "Hey Brandon! Thanks for catching this. I can reproduce it - looks like the auth refresh logic is borked. Tracking in #42." --- ❌ **Interrogative:** "Can you please provide the following information: 1) Version 2) Steps to reproduce 3) Expected behavior 4) Actual behavior" ✅ **Joel:** "Hey! Could you share which version you're on? And if you've got repro steps that'd be 🔥" --- ❌ **Over-promise:** "We'll fix this in the next patch release!" ✅ **Joel:** "On it! Should have a fix soon." ## Integration with Hive ```typescript // File cell with issue reference hive_create({ title: `Issue #42: Token refresh fails`, type: "bug", description: `https://github.com/owner/repo/issues/42 Reported by: Brandon Cheung Twitter: @justBCheung GitHub: @bcheung User reports auth tokens aren't refreshing. Repro steps in issue.` }); // When closing cell, reference in commit git commit -m "fix: token refresh race condition Fixes #42 - adds 5min buffer before token expiry. Thanks @justBCheung for the report!" ``` ## References - `scripts/get-contributor.ts` - GitHub user profile fetcher - `scripts/issue-summary.ts` - Issue details with smart formatting - GitHub CLI: `gh issue view`, `gh api users/<login>`