GitHub Issue Tracking for Developers

If It Moved
You’ll Know

One command checks every issue you’re involved in, flags what actually changed, and tells you what to do next. It remembers the details so you don’t have to.

You’re listed on issues across a dozen repos. No single place tracks which ones actually moved.

The external problem

You’re the author, a commenter, or just mentioned on issues spread across repos you don’t maintain. Some have new comments, some got closed, some got duplicated by someone else’s report, and nothing tells you which.

The internal problem

Checking in means opening each issue cold and rereading old threads just to remember what you already knew, hoping you don’t skim past the one comment that actually needed a reply.

What's at stake

A maintainer’s question sits unanswered for two weeks. You comment on an issue someone already fixed. A PR that needs your review goes stale while you’re busy elsewhere.

Five steps carry an issue from fetch to a queued action.

Run it as a one-time audit or a daily check-in. The tracker file carries context between runs, so repeat runs get faster and go deeper.

01

Discover & Fetch

Pulls every open issue you’re the author, commenter, or mentioned party on, plus anything reopened or closed since the last run, straight from the GitHub API.

02

Cross-Check Duplicates

Batches of issues get analyzed in parallel: new comments read, duplicate and related issues searched for by keyword, and PR health (merge state, CI, reviews) checked where it applies.

03

Cache to Tracker

Every fact gets written to the tracker file immediately: state changes, new duplicates, filled-in context. If the session gets interrupted here, nothing is lost.

04

Goal-Driven Next Steps

Each issue’s recommendation is driven by the goal you set for it: get a fix merged, get a maintainer to respond, or just monitor for an upstream fix.

05

Report and Act

A tight report of what changed, what’s new, and what to do today, plus queued actions the skill can run directly, like posting a comment or rebasing a PR branch, once you approve them.

Reference library: The formats and API calls it runs on.

Every fetch runs through documented gh CLI command templates instead of ad hoc queries, and every tracker write follows a strict schema for what gets overwritten versus what only fills a gap, so the tracker stays reliable across sessions.

Supporting reference files follow the practical guide. Archived source material and author workflow notes are not a current policy certification.

01 gh CLI PatternsReusable gh commands for fetching issues, comments, and PR health.

Reference

gh CLI Patterns

Issue Metadata

Fetch state, labels, comment count, timestamps:

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:

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

gh api repos/OWNER/REPO/issues/NUMBER/comments --jq '.[] | {author: .user.login, date: .created_at, body: .body}'

Comments since a date:

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

gh api repos/OWNER/REPO/issues/NUMBER --jq '.body'

Search: Issues Involving User

Open issues with recent activity:

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

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)

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:

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

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

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

gh api repos/OWNER/REPO/issues/NUMBER --jq '.state'

PR Status Check

gh api repos/OWNER/REPO/pulls/NUMBER --jq '{state: .state, merged: .merged, title: .title, updated: .updated_at}'

PR Health (run when the tracked item is a PR)

Merge-readiness, review decision, and CI status in one call:

gh pr view NUMBER --repo OWNER/REPO \
  --json state,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup,reviews

gh pr view --json resolves reviewDecision and statusCheckRollup via GraphQL under the

hood — the REST issues endpoint cannot. Use this template (not the issues endpoint) whenever

you need merge/CI/review state.

Reading the result:

  • mergeStateStatus — DIRTY means merge conflict; BLOCKED means a required check or review

is failing/missing; CLEAN/UNSTABLE means mergeable (UNSTABLE = non-required checks failing).

  • mergeable — CONFLICTING confirms a conflict; MERGEABLE is clean; UNKNOWN means GitHub

is still computing it.

  • reviewDecision — APPROVED, CHANGES_REQUESTED, or REVIEW_REQUIRED.
  • statusCheckRollup — array of checks; surface any with conclusion of FAILURE/TIMED_OUT/CANCELLED.

Review interpretation (do not misread):

  • A review with state: COMMENTED is not an approval. Only state: APPROVED counts.
  • Reviewers whose login ends in [bot] do not satisfy a human-review requirement — record

them separately from human reviews.

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.

02 Tracker SchemaDefines the tracker file format: config, pending actions, history.

Reference

Tracker Schema

File Header

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

Pending Actions Section

The authoritative, cross-session action queue. This is the only guaranteed

cross-session store for recommended actions — the harness task list (TaskList) is

session-scoped and may be empty on a fresh run, so it is never the source of truth here.

The skill reads this section at startup (Step 0) and surfaces unfinished items as

"Carried Over" in the report (Step 5a).

Placed after ## Config and before ## Active Issues:

## Pending Actions

- [ ] <action> (from owner/repo#NUMBER, YYYY-MM-DD)
- [x] <action> (YYYY-MM-DD)
Field Rules
  • `- [ ]` (unfinished): queued action not yet done. Carries over across runs until

completed. On a completed action it is flipped to - [x].

  • Queued form: - [ ] <action> (from <issue-ref>, <date>) — <issue-ref> is

owner/repo#NUMBER, <date> is the date the action was queued.

  • Completed form: - [x] <action> (<date>) — <date> is the completion date.
  • Pruning: remove - [x] items whose date is more than 7 days old. Unfinished

- [ ] items are never auto-pruned — they persist until done or explicitly dropped.

  • Completing an action also writes a ## History entry on the affected issue via

append-history (Step 5c) — the queue tracks *status*, History is the audit trail.

Active Issues Section

Each issue entry under ## Active Issues (watching for updates):

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

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

  • Only update the tracker file in Phase 4, after user confirmation.
  • Preserve manually added content. If the user added custom notes, crash data, workarounds, or other content not generated by this skill, keep it intact.
  • Move issues between sections when state changes (Active → Closed, or Closed → Active if reopened).
  • Don't remove duplicate entries — they're historical. Only add new ones.
  • 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?").
  • Append new history entries. Never remove or edit existing history entries.
03 Result File SchemaFormat each analysis agent writes so the tracker updates cleanly.

Reference

Result File Schema

Frontmatter

---
type: issue
owner: OWNER
repo: REPO
number: NUMBER
title: "Issue title"
state: open
state_changed: false           # true if state changed since last check
is_pr: false                    # true if the tracked item is a pull request
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."`

## PR Health

Conditional — include only when `is_pr: true`. Omit this entire section for plain issues.

Populated from the pr_health block in the raw JSON (or the PR-health template in

references/gh-cli-patterns.md). Record:

merge_state: CLEAN | DIRTY | BLOCKED | UNSTABLE | ...   (mergeStateStatus)
mergeable: MERGEABLE | CONFLICTING | UNKNOWN
review_decision: APPROVED | CHANGES_REQUESTED | REVIEW_REQUIRED | null
ci_status: passing | failing | pending
ci_failures: list each failing check by name (or "none")
human_reviews: @reviewer (APPROVED) — login NOT ending in [bot]
bot_reviews: @some-bot[bot] (COMMENTED) — listed separately, do NOT count toward approval

Rules:

  • state: COMMENTED is not an approval — only APPROVED counts.
  • A reviewer whose login ends in [bot] never satisfies a human-review requirement.
  • mergeStateStatus: DIRTY or mergeable: CONFLICTING means a merge conflict — surface it in

## Status Summary and ## Next Steps.

Good: `"merge_state: DIRTY (conflict in src/index.ts). ci_status: failing — 'lint' check.

review_decision: REVIEW_REQUIRED. human_reviews: none. bot_reviews: @codecov[bot] (COMMENTED)."`

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

Write discipline (mirrors SKILL.md Step 2b):

  • Always write (overwrite stale values): status_summary — it carries the API-observable,

high-churn facts (open/closed state, labels, comment count, last-comment date, and for PRs

the merge state, review decision, and CI status). Always regenerate it from fresh API data;

never preserve a stale value.

  • Fill only if missing (do not clobber human context): goal (always user-supplied — never

guess), what_to_check, and any analysis-derived context (root cause, workaround, key

technical data). Emit these only when the tracker entry has a blank for them.

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.

`TRACKER_UPDATE:` return convention (subagent → orchestrator)

history_entry: lines above are persisted in bulk by update-tracker when it reads

the result file (Step 3). That covers analysis. It does not cover an action a

subagent takes *directly* (e.g. posting a comment mid-analysis), which must be

persisted immediately rather than waiting for the end-of-session bulk write.

For those, a subagent ends its reply (not the result file) with one line per action:

TRACKER_UPDATE: owner/repo#NUMBER | YYYY-MM-DD | <one-line description>

The orchestrator parses each line and, on receipt, calls append-history once per line

before continuing:

node "$SKILL_DIR/bin/tracker-tools.cjs" append-history \
  --tracker "$TRACKER_PATH" --issue owner/repo#NUMBER \
  --date YYYY-MM-DD --desc "<one-line description>"

append-history is atomic and dedups, so a repeated line is a safe no-op. This is the

incremental, interrupt-safe path; history_entry: remains the bulk path for analysis

captured in result files.

Use it now. It's free.

Works on all platforms. Pick yours and get set up in under a minute.

Claude.ai

Download & upload in 60 seconds

Download the zip, then open Claude.ai to upload it.

01

Download the zip below. With JavaScript enabled, Claude.ai opens in a new tab if your browser allows it. Otherwise, use Open Claude.ai.

02

Click the + button in the skills column on the left.

03

Select Create a skill.

04

Select Upload a skill and upload the zip.

05

Start your issue check-in by running /estack-github-issue-tracker.

Claude Code

Run one command in any terminal

Works anywhere Node.js is installed — your project directory, home directory, anywhere.

01

Open your terminal app and run this command.

npx elliot-stack@latest
02

Run the command.

03

Start Claude Code by typing claude in your terminal.

04

Start your issue check-in by running /estack-github-issue-tracker.

ChatGPT / Other

Paste a prompt — the AI does the rest

This prompt tells the AI where to fetch current instructions from the live site. No installs. No version lag.

01

Copy the prompt below.

Preview prompt
<objective>
Give the user a complete, actionable update on every GitHub issue they're involved in.
One flow, every time — no modes, no flags. The only thing that changes between runs is
depth: more work when the tracker is empty or stale, less when it was just checked yesterday.
</objective>

<execution_context>
Resolve `$SKILL_DIR` from this file's location FIRST.

**Script:** `https://elliotdrel.com/e-stack/github-issue-tracker/bin/tracker-tools.cjs` — handles all GitHub API calls, tracker parsing,
report compilation, and tracker updates. Invoke via:

```bash
node "$SKILL_DIR/bin/tracker-tools.cjs" <command> [options]
```

Every script command returns a `today` field like `today's date is **2026-04-05**, ignore earlier dates`.
Extract the date from this string. If you see multiple `today` values in your context
(from earlier commands), always use the most recent one.

**stdout/stderr convention:** `compile-report` outputs the report text to stdout and
metadata (including `today`) to stderr. Parse accordingly.

**Tracker file:** `$HOME/OneDrive/Documents/github-tracker.md`
This is the AI's knowledge base and source of truth. It stores everything in full detail:

- Every tracked issue with complete context, history, and technical data
- Known duplicates, related issues, cross-references
- User's intent/goals for each issue and what to watch for
- History of all actions taken and events observed
- Config directives (excluded repos, preferences)

The tracker is written FOR the AI — keep it detailed. When the user asks questions about
any issue, read the tracker first. It should have enough context to answer without
re-fetching from GitHub. The user-facing report (Step 5a) is a separate, concise summary.

**References:**

- `https://elliotdrel.com/e-stack/github-issue-tracker/references/tracker-schema.md` — tracker file format
- `https://elliotdrel.com/e-stack/github-issue-tracker/references/result-file-schema.md` — per-issue analysis format (agents write these)
- `https://elliotdrel.com/e-stack/github-issue-tracker/references/gh-cli-patterns.md` — gh CLI command templates
- `https://elliotdrel.com/e-stack/github-issue-tracker/tracker-template.md` — blank tracker for first run
</execution_context>

<flow>

The skill runs the same steps every time. The tracker determines depth — an empty
tracker means everything is new and needs deep analysis. A fresh tracker means most
issues just need a quick diff check.

## Step 0: Startup

1. Set `$TRACKER_PATH` to `$HOME/OneDrive/Documents/github-tracker.md`.
2. Run startup:
   ```bash
   node "$SKILL_DIR/bin/tracker-tools.cjs" startup --tracker "$TRACKER_PATH"
   ```
3. Store the full response as `$STARTUP`. The script handles auth checking and temp dir
   creation. If `auth` is false, show the user the `error` message from the output and STOP.
   If `search_errors` is non-empty, warn the user that some discovery queries failed —
   the results may be incomplete.
4. Extract `$TODAY` (the YYYY-MM-DD date) from the `$STARTUP.today` string — use this as today's date for everything.
5. Extract `$TEMP_DIR` from `$STARTUP.temp_dir`.
6. Extract `$CONFIG` from `$STARTUP.config`. This is the user's plain English config
   (excluded repos, preferences, etc.) parsed from the tracker's `## Config` section.
   If null, the tracker has no config yet — you'll ask the user in Step 1.
7. Read the tracker's `## Pending Actions` section into `$PENDING_ACTIONS` (read it
   directly from `$TRACKER_PATH` with the Read tool; if the section or file is absent,
   treat it as empty). Every unfinished `- [ ]` item is an action carried over from a
   prior run — Step 5a surfaces these as "Carried Over". This tracker section is the
   **authoritative cross-session action queue**: the tracker file is the only guaranteed
   cross-session store. Do **not** read carried-over actions from the harness task list
   (`TaskList`) — it is session-scoped and may be empty on a fresh CLI session.

---

## Step 1: Discover

**Goal:** Build the complete list of issues to analyze this run.

Sources (all from `$STARTUP`):

- `tracker_data.active_issues` — issues already tracked
- `new_issues` — open issues involving the user that aren't in the tracker yet
- `reopened_issues` — issues previously closed that are now open again
- `recently_closed` — issues closed since last check

**Check `$CONFIG` from startup.** If it contains directives (excluded repos, preferences),
apply them when filtering issues throughout this step. For example, if config says
"Excluded repos: ElliotDrel/*", skip any issues from repos owned by ElliotDrel.

If `$CONFIG` is null (tracker has no Config section), ask the user if they want to set
one up (which repos to track/exclude). The agent writes Config directly to the tracker
file via the Edit tool (not through the script). The script reads Config; the agent writes it.

**If tracker doesn't exist or has no issues** (first run):

- Show `new_issues` grouped by repo. List which repos were found.
- Ask: "Which repos do you want to track? You can also exclude any."
- Save their choices to the `## Config` section by writing directly to the tracker via Edit.
- Then ask which specific issues to track from the included repos.

**If tracker exists with issues:**

- Active issues are automatically included (unless excluded by config).
- If `new_issues` is non-empty and passes config filters, tell the user what was
  found and add them to the analysis list.
- If `reopened_issues` is non-empty, add them back to the active analysis list and
  note in your report that they were reopened (state changed from closed to open).
  The agent should manually move reopened issues from the Closed section back to
  Active in the tracker, preserving any context from the closed entry.

Write the final issue list to `$TEMP_DIR/issues-to-fetch.json` for the fetch command.
Each entry needs: `owner`, `repo`, `number`, `title`, `role`, `last_check_date`
(null for new issues), `known_dupes` (from tracker or empty), `upstream` (from tracker or null).

---

## Step 2: Connect

**Goal:** Fetch current data for every issue and find related/duplicate issues.

### 2a: Fetch all issue data

```bash
node "$SKILL_DIR/bin/tracker-tools.cjs" fetch-issues --temp-dir "$TEMP_DIR" --issues "$TEMP_DIR/issues-to-fetch.json"
```

This fetches metadata, body, comments, dupe states, upstream state, cross-references,
and URLs for every issue in parallel. One `raw-OWNER-REPO-NUMBER.json` per issue.

### 2b: Analyze issues in batches

Read `https://elliotdrel.com/e-stack/github-issue-tracker/references/result-file-schema.md` and `https://elliotdrel.com/e-stack/github-issue-tracker/references/gh-cli-patterns.md` from `$SKILL_DIR`.

Group issues into batches of ~5. Spawn **one Agent per batch**. Each agent:

1. Reads the raw JSON files for its batch issues.
2. Searches for duplicates/related issues using `gh api` search queries.
3. Writes one result file per issue to `$TEMP_DIR/issue-OWNER-REPO-NUMBER.md` following
   the format in `https://elliotdrel.com/e-stack/github-issue-tracker/references/result-file-schema.md`.

**Depth control based on `last_check_date`:**

The duplicate/related search always runs, but the scope changes:

- **`null` (new issue):** Deep analysis. Read full comment history. Search broadly for
  duplicates by symptoms, error messages, and keywords.
- **Checked within the last 7 days:** Shallow pass. Only read new comments since last check.
  Only check the state of already-known duplicates/related issues. Only search for new
  duplicates among issues created since the last check date.
- **Checked more than 7 days ago:** Medium depth. Read comments since last check. Re-scan
  for new duplicates across a wider window. Check state of known duplicates.

**Reconcile tracker against the API — two categories:** For each issue, compare what the
tracker has against what the API returned. Sort every field into one of two buckets:

- **Always re-fetch and overwrite** (API-observable, high-churn — never trust the tracker
  for these): open/closed `state`, `labels`, `comment_count`, last-comment date,
  `mergeStateStatus`, `mergeable`, `reviewDecision`, CI status. A wrong-but-present value
  (e.g. a PR previously marked "approved") **must** be overwritten with the fresh API value,
  not preserved.
- **Fill only if missing** (human analysis, low-churn): Goal, root cause, Workaround, Key
  technical data, Role description. Populate these from the API/analysis only when the tracker
  entry has a blank — never clobber existing human-authored context.

Include both overwritten and newly populated fields in the result file's `## Tracker Updates`
section. Every run thus refreshes volatile facts and progressively fills analysis gaps.

**If the item is a PR** (raw JSON has a non-null `pr_health` block — see Step 2a), fetch the
PR-health template from `gh-cli-patterns.md` if `pr_health` is missing, and record merge state,
review decision, and CI status in `## Status Summary`, the `## PR Health` section, and
`## Next Steps`. Distinguish bot reviews (login ends in `[bot]`) from human reviews, and treat
`COMMENTED` ≠ `APPROVED` — a `COMMENTED` review is not an approval.

**Exception — fields that require user input:** The **Goal** field must be asked, not
guessed. If an issue is missing a Goal, flag it in the result file so Step 5d can
collect them. Same for Config — never assume repo exclusions or preferences, always ask.

Each agent prompt must include:

- Raw data file paths for its batch
- The existing tracker entry data for each issue (so the agent can identify gaps)
- `owner`, `repo`, `number`, `title`, `role`, `last_check_date`, `username`
- `cross_references` and `urls` from raw JSON
- All tracked issue numbers (to filter dupe search results)
- `$TODAY` as today's date (for history entries)
- Instruction to read `$SKILL_DIR/references/result-file-schema.md` for format and quality guidance

**Subagent return convention.** Each agent's analysis is persisted by `update-tracker`
(Step 3) reading the result files — agents do **not** call `append-history` themselves.
But if an agent takes a tracker-relevant action directly (rare in 2b), it must end its
reply with one line per action so the orchestrator can persist it incrementally:

```
TRACKER_UPDATE: owner/repo#NUMBER | YYYY-MM-DD | <one-line description>
```

On receipt, the orchestrator calls `append-history` once per `TRACKER_UPDATE:` line
(`--issue owner/repo#NUMBER --date YYYY-MM-DD --desc "<description>"`) before continuing.

After all agents finish, verify file count:

```bash
ls "$TEMP_DIR"/issue-*.md 2>/dev/null | wc -l
```

---

## Step 3: Save

**Goal:** Immediately persist all factual data from the analysis to the tracker.

This step is **mandatory and automatic** — no user permission needed. The analysis just
finished and the result files contain factual data from the GitHub API. This step caches
that data in the tracker so that even if the conversation is interrupted after this point,
the tracker has the latest information.

**If this is the first run** (no tracker existed):

```bash
node "$SKILL_DIR/bin/tracker-tools.cjs" build-tracker --temp-dir "$TEMP_DIR" --template "$SKILL_DIR/tracker-template.md" --username "$USERNAME" --tracker "$TRACKER_PATH" --date "$TODAY"
```

**If the tracker already exists:**

```bash
node "$SKILL_DIR/bin/tracker-tools.cjs" update-tracker --tracker "$TRACKER_PATH" --temp-dir "$TEMP_DIR" --date "$TODAY"
```

This saves: status dates, new comments, new duplicates, filled data gaps, state changes.

**Every tracker update must be logged in History.** Every change the script makes to the
tracker — new fields populated, status updates, new duplicates found — gets a history
entry on the affected issue. The History section is an append-only audit trail. Examples:
- `**2026-04-06:** Check-in: no new activity`
- `**2026-04-06:** Filled in missing Workaround and Key technical data fields`
- `**2026-04-06:** Found new duplicate #45123`
- `**2026-04-06:** Status changed: open → closed`

---

## Step 4: Advise

**Goal:** Identify concrete next steps for each issue before presenting the report.

Read through all result files in `$TEMP_DIR/issue-*.md`. For each issue, use the
**Goal** field from the tracker (e.g., "Get my fix merged", "Get maintainer to respond",
"Monitor for upstream fix") to tailor recommendations. The goal tells you what success
looks like — next steps should move toward that outcome.

For each issue, determine:

- Given the user's goal, what action would move this issue forward?
- Are there related issues where commenting with a link to the user's issue would help?
- Are there duplicates the user should reference or link to?
- Is there a PR fixing the issue that needs testing or review?

Collect all next steps. These get included in the report output.

---

## Step 5: Report and Act

**Goal:** Show the user what's going on and help them take action.

### 5a: Report

```bash
node "$SKILL_DIR/bin/tracker-tools.cjs" compile-report --temp-dir "$TEMP_DIR" --date "$TODAY"
```

The script outputs the report text to stdout and metadata (including `today`) to stderr.
Use the stdout output as raw data, but present the report to the user in YOUR response
using the format below.

**Carried Over (from `$PENDING_ACTIONS`).** If `$PENDING_ACTIONS` (read at Step 0) has
any unfinished `- [ ]` items, **prepend** a `## Carried Over` section to the report
listing them verbatim — these are actions queued in a prior run that were never executed
or completed. Omit the section entirely when there are no unfinished items. This list
comes from the tracker's `## Pending Actions` section, never from the harness task list.

**Report format — keep it tight and actionable:**

The user wants to know three things: what changed, what's the update, what do I do.
Skip GitHub spam (bot comments, auto-close noise, label changes). Use bullets, not tables.

```
# Check-In — {date}

## Carried Over
- unfinished `- [ ]` action from a prior run (omit this whole section if there are none)

## What Changed
- bullet per issue that had real activity (new human comments, state changes, PRs)
- if nothing changed, say "No new activity across N tracked issues."

## New Issues Found
- bullet per newly discovered issue (if any, after config filtering)

## Recommended Actions
### Do Today
- specific action items the user should take right now
### Watch For
- things that might need attention soon but not today
### No Action Needed
- brief grouped summary of issues that are just waiting (e.g., "15 google-tools-mcp issues — no maintainer response")
```

Do NOT list every single issue with its full status. Only mention issues where
something happened or something needs to happen. Group quiet issues into one line.

### 5b: Persist actions to the queue

The `## Pending Actions` section of the tracker is the **authoritative, cross-session
action queue** — the source of truth. Write **every** "Do Today" item from the 5a report
into it, one line each, using the Edit tool:

```
- [ ] <action> (from <issue-ref>, <date>)
```

Use `$TODAY` for `<date>` and the `owner/repo#NUMBER` form for `<issue-ref>`. If the
`## Pending Actions` section does not exist yet, create it (see
`https://elliotdrel.com/e-stack/github-issue-tracker/references/tracker-schema.md` for placement and format). Carried-over `- [ ]` items
from prior runs that are still relevant stay in place — do not duplicate them.

**Optional within-session mirror.** You may mirror these items to the harness task list
(`TaskCreate`) for within-session focus, but it is a convenience only — never the source
of truth. The harness task list is session-scoped and may be empty on a fresh CLI
session, so "Carried Over" (Step 5a) and the queue itself always read from the tracker
section, never from `TaskList`.

### 5c: Execute approved actions

Present the queued items to the user and ask whether to act on them (e.g. "Want me to
act on these? I'll do all of them." or per-item). If the user declines, leave the items
as `- [ ]` in the queue — they carry over to the next run. If the user approves (a
blanket "do all of them" approves the whole batch), run the execution framework below
against the 5b queue.

1. **Mark before acting.** Flip the queue item you're about to work on to in-progress
   (note it inline, e.g. `- [~]`, or mark the mirrored harness task `in_progress` if you
   created one). Do this before any work starts so an interruption leaves a clear trail.

2. **Parallel subagents — one per approved action.** Spawn one Agent per approved queue
   item so independent actions run concurrently.

3. **Action-type routing table.** Route each action by type:

   | Action | Execution |
   |---|---|
   | Post comment / tag maintainer | `gh pr comment` / `gh issue comment` directly — no clone |
   | Rebase a PR branch | clone fork → temp dir → add upstream remote → rebase → force-push → `rm -rf` |
   | Fix PR review blockers | clone branch → temp dir → make change → push → re-request review → `rm -rf` |
   | Watch / monitor | no action; note it in the report |

4. **Temp-dir-only for git.** Any `git clone` goes into a fresh `mktemp -d` directory;
   do the work there and `rm -rf` it when done. **Never** clone into the user's working
   directory.

5. **Force-push auth.** A blanket "do all of them" approval authorizes force-pushing the
   rebased PR branches in this batch. Do **not** re-ask for permission per branch.

6. **Subagent model.** Follow the global subagent cascade (one tier below the
   orchestrator). For complex code-fixing tasks (unfamiliar repo plus test infrastructure),
   floor the model at Sonnet even if the cascade would otherwise pick Haiku.

7. **Report back + persist immediately.** Each agent returns what it did: conflicts
   resolved, push/comment success, and any blockers. As **each** action completes,
   **immediately** record it with `append-history` for that issue — do not batch, do not
   wait until the end of the session, and do not use `Edit` for history (`append-history`
   is atomic and dedup'd; this is the same incremental-persistence invariant the rest of
   the skill follows):

   ```bash
   node "$SKILL_DIR/bin/tracker-tools.cjs" append-history \
     --tracker "$TRACKER_PATH" --issue OWNER/REPO#NUMBER \
     --date "$TODAY" --desc "description of the action"
   ```

   Re-running the same entry is a safe no-op (it dedups). If the command exits non-zero
   because the issue section is not found, the tracker is left unchanged — surface the
   error, fix the issue key, and retry; do not fall back to `Edit`.

   Then flip the queue item in `## Pending Actions` from `- [ ]` (or `- [~]`) to
   `- [x] <action> (<date>)` via the Edit tool, and mark the mirrored harness task
   complete if you created one. **Prune** any `- [x]` items whose date is more than 7 days
   old from the section.

   If a subagent reports actions via `TRACKER_UPDATE:` lines (see Step 2b and
   `https://elliotdrel.com/e-stack/github-issue-tracker/references/result-file-schema.md`), call `append-history` once per line as soon as you
   receive them — one line maps to one `--issue` / `--date` / `--desc` invocation.

**Tracker-relevant action set** (each one triggers an immediate `append-history`):

- Comment posted (`gh issue comment` / `gh pr comment`)
- Issue or PR linked/cross-referenced from another issue
- Goal set or changed for an issue
- State change applied or observed (open → closed, reopened, etc.)
- PR filed, pushed, or rebased for an issue
- Config change written to the tracker

Examples of the `--desc` text:
- `Posted comment on #1234 linking to duplicate #5678`
- `Rebased PR branch onto upstream/main and force-pushed`
- `Goal set: "Get maintainer to respond"`
- `Added Config section to tracker (excluded: ElliotDrel/*)`

### 5d: Collect missing Goals

If result files flagged issues without a Goal, present them to the user grouped by repo
and ask what their intent is for each. Example: "These issues don't have a goal set
yet — what are you hoping for with each?"

Once the user provides goals, write them directly to the tracker file via the Edit tool
(not through the script). Log the *action* with `append-history` (not `Edit`) for each
goal set — the field value goes in via `Edit`, the history entry via `append-history`:
- `**2026-04-06:** Goal set: "Get maintainer to respond"`

### 5e: Cleanup

```bash
rm -rf "$TEMP_DIR"
```

</flow>

<context>
$ARGUMENTS
</context>

---

## Skill Feedback

If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:

**If `gh` is installed** (`gh --version` succeeds), create the issue directly:

```bash
gh issue create \
  --repo ElliotDrel/e-stack \
  --title "estack-github-issue-tracker: <concise summary>" \
  --body "<description from user feedback — expected vs. actual behavior and context>"
```

**If `gh` is not installed**, build a pre-filled URL:

```bash
python3 -c "
import urllib.parse
title = 'estack-github-issue-tracker: <concise summary>'
body = '<description from user feedback — expected vs. actual behavior and context>'
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
"
```

Share the printed URL with the user and offer to open it in their browser.

They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
02

Open your platform and paste the prompt.

03

Start your issue check-in.

GitHub Issue Tracker ships in E-Stack, a set of 21 free skills installed by one command. See the whole stack.