elliot-stack 1.0.0

package/skills/github-issue-tracker/references/gh-cli-patterns.md

@@ -0,0 +1,124 @@
+# gh CLI Patterns
+
+Reusable command templates for all GitHub API calls in this skill. Replace CAPS placeholders
+with actual values.
+
+---
+
+## Issue Metadata
+
+Fetch state, labels, comment count, timestamps:
+```bash
+gh api repos/OWNER/REPO/issues/NUMBER --jq '{state: .state, labels: [.labels[].name], comments: .comments, updated: .updated_at, created: .created_at}'
+```
+
+## Issue Comments
+
+Last 3 comments with author, date, full body:
+```bash
+gh api repos/OWNER/REPO/issues/NUMBER/comments --jq '.[-3:] | .[] | {author: .user.login, date: (.created_at | split("T")[0]), body: .body}'
+```
+
+All comments (for drafting — verify claims before posting):
+```bash
+gh api repos/OWNER/REPO/issues/NUMBER/comments --jq '.[] | {author: .user.login, date: .created_at, body: .body}'
+```
+
+Comments since a date:
+```bash
+gh api repos/OWNER/REPO/issues/NUMBER/comments --jq '[.[] | select(.created_at > "DATE")] | .[] | {author: .user.login, date: (.created_at | split("T")[0]), body: .body}'
+```
+
+**Truncation rules:** Never truncate comments on the primary issue being reviewed — technical
+details (addresses, error codes, test counts) get lost. For secondary fetches (known
+duplicates, upstream), `[0:1500]` is acceptable to manage context size.
+
+## Issue Body
+
+Full issue body (read before commenting on unfamiliar issues):
+```bash
+gh api repos/OWNER/REPO/issues/NUMBER --jq '.body'
+```
+
+## Search: Issues Involving User
+
+Open issues with recent activity:
+```bash
+gh api "search/issues?q=involves:USERNAME+updated:>DATE+is:open" --jq '.items[] | "#\(.number) \(.repository_url | split("/") | .[-2:] | join("/")) — \(.title) [updated: \(.updated_at)]"'
+```
+
+## Search: Issues by Author
+
+```bash
+gh api "search/issues?q=author:USERNAME+is:open&per_page=100&sort=updated" --jq '.items[] | "#\(.number) \(.repository_url | split("/") | .[-2:] | join("/")) — \(.title) [updated: \(.updated_at | split("T")[0])]"'
+```
+
+## Search: Issues by Commenter (excluding authored)
+
+```bash
+gh api "search/issues?q=commenter:USERNAME+is:open+-author:USERNAME&per_page=100&sort=updated" --jq '.items[] | "#\(.number) \(.repository_url | split("/") | .[-2:] | join("/")) — \(.title) [updated: \(.updated_at | split("T")[0])]"'
+```
+
+## Search: Keyword Search for Duplicates
+
+Search for issues matching keywords, created after a specific date:
+```bash
+gh api "search/issues?q=repo:OWNER/REPO+is:open+created:>DATE+KEYWORD1+KEYWORD2&per_page=10" --jq '.items[] | "#\(.number) — \(.title) [\(.created_at | split("T")[0])] @\(.user.login)"'
+```
+
+Use multiple keyword variations per search to catch different phrasings. Example for an OAuth issue:
+- Search 1: `OAuth redirect MCP`
+- Search 2: `clientId mcp add`
+- Search 3: `Slack plugin authentication`
+
+## Search: Recently Closed Issues
+
+```bash
+gh api "search/issues?q=involves:USERNAME+is:closed+closed:>DATE&per_page=50&sort=updated" --jq '.items[] | "#\(.number) \(.repository_url | split("/") | .[-2:] | join("/")) — \(.title) [closed: \(.closed_at | split("T")[0])]"'
+```
+
+## Post Comment
+
+```bash
+gh issue comment NUMBER --repo OWNER/REPO --body "$(cat <<'EOF'
+Comment body here.
+Supports **markdown**.
+EOF
+)"
+```
+
+Always use heredoc (`<<'EOF'`) for comment bodies to handle special characters and newlines.
+
+## Quick State Check
+
+Check if an issue is still open (fast, minimal data):
+```bash
+gh api repos/OWNER/REPO/issues/NUMBER --jq '.state'
+```
+
+## PR Status Check
+
+```bash
+gh api repos/OWNER/REPO/pulls/NUMBER --jq '{state: .state, merged: .merged, title: .title, updated: .updated_at}'
+```
+
+---
+
+## Rate Limiting
+
+GitHub API has rate limits. If running many parallel requests:
+- Authenticated requests: 5000/hour
+- Search API: 30 requests/minute
+- If you hit limits, batch searches and add short delays between search batches
+- Metadata fetches (repos/OWNER/REPO/issues/NUMBER) don't count against search limits
+
+## Parallel Execution Strategy
+
+To maximize speed, batch API calls by type:
+
+**Batch 1 (parallel):** All active issue metadata + comments (these are REST calls, not search)
+**Batch 2 (parallel):** All known duplicate/related issue checks (REST calls)
+**Batch 3 (parallel):** All keyword searches for new duplicates (search API — respect 30/min limit)
+**Batch 4 (parallel):** User involvement search + closed issue checks + upstream checks
+
+Batches 1 and 2 can run simultaneously. Batch 3 should start after a brief pause if Batch 1+2 included many calls. Batch 4 can run with Batch 1.

package/skills/github-issue-tracker/references/result-file-schema.md

@@ -0,0 +1,156 @@
+# Result File Schema
+
+> Written by analysis agents, consumed by `compile-report`, `build-tracker`, and `update-tracker`.
+
+One file per issue: `issue-OWNER-REPO-NUMBER.md` in the temp directory.
+Raw API data lives in `raw-OWNER-REPO-NUMBER.json` (written by `fetch-issues`).
+
+---
+
+## Frontmatter
+
+```yaml
+---
+type: issue
+owner: OWNER
+repo: REPO
+number: NUMBER
+title: "Issue title"
+state: open
+state_changed: false           # true if state changed since last check
+labels: label1, label2
+has_activity: false             # true if new comments since last check
+role: "SEE GUIDANCE BELOW"
+filed: YYYY-MM-DD
+last_check_date: null           # date of previous check, null for first analysis
+last_commenter: "@username"
+last_comment_date: YYYY-MM-DD
+comment_count: N
+---
+```
+
+### Role Field
+
+The role MUST describe what the user **did**, not just a label.
+
+Bad: `"Author"`, `"Commenter"`
+Good: `"Author (filed with 3 crash instances, posted workaround)"`,
+`"Commenter (confirmed bug + shared exact callbackPort: 3118 fix)"`
+
+---
+
+## Body Sections
+
+### ## Status Summary
+
+Plain English: where does this issue stand and why does it matter? Write as if briefing
+someone who hasn't looked at the issue in a week. Include dates, names, numbers.
+
+Bad: "Issue is about a bug that causes crashes."
+Good: "You filed this on Jan 15 about a crash when renaming MCP servers. Root cause is
+tracked upstream in bun#28175. Workaround: name servers differently."
+
+### ## Activity
+
+What happened since last check (or full history if first analysis).
+
+Format:
+```
+- @username (YYYY-MM-DD): What they said WITH specifics.
+```
+
+### ## Duplicates and Related
+
+Two subsections:
+
+#### ### Known — updates
+Status changes on previously known duplicates/adjacent issues. Or "No changes."
+
+#### ### New finds
+Newly discovered duplicates or related issues. Or "None found."
+
+For each entry, explain whether it shares a **root cause** (duplicate) or just
+**symptoms** (adjacent). Don't just list titles — explain WHY it's related.
+
+Bad: `"#40693 — related rename issue"`
+Good: `"#40693 — VS Code UI blocking during rename. Same symptom (rename fails) but
+different root cause: UI thread blocking vs JSONL write. Adjacent, not duplicate."`
+
+### ## Upstream
+
+Upstream dependency status — is this issue blocked on or related to an upstream fix?
+Write "N/A" if there are no upstream dependencies.
+
+Bad: `"There's an upstream issue."`
+Good: `"Blocked on bun#28175 (open, no activity since Mar 2). Fix landed in Node 22.4 but
+Bun hasn't ported it. No workaround available upstream."`
+
+### ## Cross-References
+
+All issue numbers mentioned in the issue body and comments. Helps the tracker build
+a cross-reference map. List each with a one-line explanation of why it was mentioned.
+
+Bad: `"#100, #200, #300"`
+Good:
+```
+- #28175 — upstream Bun issue causing the root crash
+- #40693 — adjacent rename bug (different root cause, shared symptom)
+- #41022 — PR that attempted a fix but was reverted
+```
+
+### ## Next Steps
+
+Specific, actionable items driven by the user's **Goal** for this issue (from the tracker).
+If the goal is "get my fix merged", focus on what's blocking the merge.
+If "get maintainer to respond", suggest ways to increase visibility.
+If "monitor for upstream fix", focus on upstream signals.
+
+Bad: `"Monitor for updates"`, `"Follow up"`
+Good: `"Respond to @maintainer's request for memory profiling data"`,
+`"Test fix in PR #4521 against your reproduction case"`,
+`"Nothing to do — waiting on maintainer review. Check back next week."`
+
+### ## Watch For
+
+Specific, concrete signals to monitor for this issue. These drive what gets checked
+on the next run. Avoid generic statements — name exact PRs, labels, or events.
+
+Bad: `"Watch for updates"`, `"Monitor the repo"`
+Good:
+```
+- PR #4521 merging (would fix root cause)
+- `p0` label being added (escalation signal)
+- @core-dev responding to the reproduction request from Mar 28
+```
+
+### ## Key Context
+
+Workarounds (exact commands, not paraphrases), severity signals, technical details
+someone would need to discuss this issue knowledgeably.
+
+Bad: `"Use different server names"`
+Good: `"Workaround: set MIMALLOC_ARENA_EAGER_COMMIT=0 before starting. Reduces peak
+RSS from 2.4GB to 1.1GB but doesn't eliminate growth."`
+
+### ## Tracker Updates
+
+Machine-readable lines consumed by `update-tracker` and `build-tracker`:
+
+```
+goal: Get my fix merged | Get maintainer response | Monitor for upstream fix | etc.
+status_summary: Open. Labels: bug, p1. JSONL crash on rename. 12 comments total.
+what_to_check: PRs modifying renameSession; JSONL title write logic changes.
+```
+
+Optional:
+```
+new_duplicate: #NUMBER — @author, "Title" (date). Why related. [duplicate|adjacent]
+```
+
+History entries (one per notable event):
+```
+history_entry: YYYY-MM-DD | Description of action or event
+```
+
+What to log: actions taken ("Posted comment"), external events ("Maintainer replied"),
+state changes ("Closed via PR #123"). Don't log "no activity" — only real events.

package/skills/github-issue-tracker/references/tracker-schema.md

@@ -0,0 +1,96 @@
+# Tracker File Schema
+
+Defines the format and fields for `github-tracker.md`.
+
+---
+
+## File Header
+
+```markdown
+# GitHub Issue Tracker
+
+GitHub username: **USERNAME**
+
+## Config
+
+Tracked repos: all repos where I'm involved
+Excluded repos: none
+
+---
+```
+
+## Config Section
+
+Plain English directives that control what the skill tracks and how it reports.
+The skill reads these on every run and respects them when filtering issues.
+
+Common directives:
+- `Tracked repos:` — which repos to include (default: all involving user)
+- `Excluded repos:` — repos to skip entirely (e.g., `ElliotDrel/*` to skip own repos)
+- Any other plain English instructions (e.g., "Don't show bot comments", "Focus on bugs only")
+
+The skill treats these as soft rules — it reads them and applies judgment. No rigid parsing.
+
+## Active Issues Section
+
+Each issue entry under `## Active Issues (watching for updates)`:
+
+```markdown
+### owner/repo#NUMBER — Title
+- **Goal:** What the user wants from this issue (e.g., "Get my fix merged", "Get maintainer to respond", "Monitor for upstream fix"). Drives next-step recommendations.
+- **Role:** Author | Commenter | Mentioned (brief description of involvement)
+- **Filed:** YYYY-MM-DD (only if authored by user)
+- **Status as of YYYY-MM-DD:** Open/Closed. Labels: label1, label2. Summary of current state. N comments total.
+- **What to check:** Specific signals to watch for (e.g., "Any Anthropic response?")
+- **Related:** #other, #issues (cross-references found in comments)
+- **Upstream:** owner/repo#NUMBER (if tracking an upstream dependency)
+- **Crash instances:** (optional, for bug reports with multiple data points)
+  1. Description of instance
+  2. Description of instance
+- **Workaround:** Description of workaround (if applicable)
+- **Duplicates found (YYYY-MM-DD):**
+  - **#NUMBER** — @author, "Title" (date). Why it's related/duplicate.
+- **Adjacent issues found (YYYY-MM-DD):**
+  - **#NUMBER** — @author, "Title" (date). Why it's adjacent (same space, different problem).
+- **Next steps (now):** Immediate actions for this check-in.
+- **Future:** Things to monitor or do later.
+- **History:**
+  - **YYYY-MM-DD:** Filed issue with 3 crash instances, upstream tracking in bun#28175
+  - **YYYY-MM-DD:** Posted workaround (callbackPort: 3118 fix)
+  - **YYYY-MM-DD:** Maintainer @user replied with fix proposal
+```
+
+### Field Rules
+
+- **"Status as of" date:** Always update to today's date during Phase 4.
+- **"Duplicates found" date:** Date when the duplicate was first identified. Don't change on subsequent check-ins.
+- **"Next steps (now)":** Clear after execution. If not executed, carry forward.
+- **"Future":** Accumulates over time. Remove items that become "Next steps (now)" or are no longer relevant.
+- **"Goal":** Set on first add, update if the user's intent changes. Use this to drive next-step recommendations — if the goal is "get merged" the next steps focus on what's blocking the merge; if "monitor for fix" the next steps focus on upstream signals.
+- **Role descriptions:** Keep brief. Examples: "confirmed bug + posted workaround", "shared skill + reported 64KB bug", "proposed configurable keybindings".
+- **"History:"** Append-only timestamped log. Format: `- **YYYY-MM-DD:** Action or event description`. Newest entries go last (chronological). Logs both our actions (filing, commenting, posting workarounds) and detected external events (maintainer replies, state changes, PRs merged). On initial filing, first entry must be: `- **YYYY-MM-DD:** Filed issue` (or `Added to tracker` if not authored by user).
+
+## Closed / Resolved Section
+
+Each entry under `## Closed / Resolved`:
+
+```markdown
+### owner/repo#NUMBER — Title
+- Brief resolution note (merged, auto-closed as duplicate of #X, fixed in vX.Y.Z, etc.)
+- Date closed if notable.
+```
+
+## Morning Check-In Procedure Section
+
+Static section with reusable `gh` CLI commands. Update USERNAME if it changes. Otherwise don't modify.
+
+---
+
+## Update Rules
+
+1. **Only update the tracker file in Phase 4, after user confirmation.**
+2. **Preserve manually added content.** If the user added custom notes, crash data, workarounds, or other content not generated by this skill, keep it intact.
+3. **Move issues between sections** when state changes (Active → Closed, or Closed → Active if reopened).
+4. **Don't remove duplicate entries** — they're historical. Only add new ones.
+5. **Keep "What to check" relevant.** Update if the situation changed (e.g., if Anthropic responded, change from "Any Anthropic response?" to "Follow up on Anthropic's suggestion?").
+6. **Append new history entries. Never remove or edit existing history entries.**

package/skills/github-issue-tracker/tracker-template.md

@@ -0,0 +1,58 @@
+# GitHub Issue Tracker
+
+GitHub username: **USERNAME_HERE**
+
+## Config
+
+<!-- Directives for the check-in skill. Write in plain English. Examples:
+- "Skip issues on my own repos (ElliotDrel/*)"
+- "Only track issues on anthropics/claude-code and oven-sh/bun"
+- "Don't show me bot comments or auto-close spam"
+-->
+
+Tracked repos: all repos where I'm involved
+Excluded repos: none
+
+---
+
+## Active Issues (watching for updates)
+
+<!-- For each issue you're tracking, use this format:
+
+### owner/repo#NUMBER — Title
+- **Role:** Author | Commenter | Mentioned (brief description of involvement)
+- **Filed:** YYYY-MM-DD (if authored by you)
+- **Status as of YYYY-MM-DD:** Open/Closed. Labels: ... . Summary of current state.
+- **What to check:** What signals matter for this issue?
+- **Related:** #other, #issues (if any)
+- **Upstream:** owner/repo#NUMBER (if tracking an upstream dependency)
+- **Duplicates found (YYYY-MM-DD):**
+  - **#NUMBER** — @author, "Title" (date). Why it's related.
+- **Next steps (now):** Immediate actions to take this check-in.
+- **Future:** Things to monitor or do later.
+- **History:**
+  - **YYYY-MM-DD:** Filed issue (or "Added to tracker for monitoring")
+-->
+
+## Closed / Resolved
+
+<!-- For each resolved issue:
+
+### owner/repo#NUMBER — Title
+- Brief resolution note (merged, auto-closed as duplicate, etc.)
+-->
+
+---
+
+## Morning Check-In Procedure
+
+Run this to get a quick status update on all active issues:
+
+```bash
+gh api search/issues?q=involves:USERNAME_HERE+updated:>$(python3 -c "import datetime; print((datetime.datetime.now()-datetime.timedelta(days=7)).strftime('%Y-%m-%d'))")+is:open --jq '.items[] | "#\(.number) \(.repository_url | split("/") | .[-2:] | join("/")) — \(.title) [updated: \(.updated_at)]"'
+```
+
+Then for each issue, check recent comments:
+```bash
+gh api repos/OWNER/REPO/issues/NUMBER/comments --jq '.[-3:] | .[] | "[\(.created_at)] @\(.user.login): \(.body[0:200])"'
+```