---
name: github-inbox
description: "Collect and triage a GitHub work inbox from assigned issues, review requests, mentions, authored PRs with failing checks, and optional project filters. Use when checking what needs attention across GitHub or prioritizing GitHub tasks."
compatibility: Requires GitHub CLI gh access. The bundled inbox report script runs with Node.js or Bun.
allowed-tools: Bash(gh *) Bash(node *) Bash(bun *)
metadata:
  version: "2.0.0"
  tags: "github, inbox, triage, issues, pull-requests"
---

# GitHub Inbox

Turn scattered GitHub work into a small priority queue.

## Authorized Scope

Apply this engine only within the user's requested task and existing explicit
authorization. Loading or delegating to it grants no additional authority.
Preserve report-only restrictions and the caller's target, host, provider, and
cost limits. Existing approval satisfies a gate only for the same actions and
scope; obtain approval before expanding them. Forward these limits to delegates.

## Contract

Inputs:

- Optional repository, owner, or project filter
- Optional limit and priority rules

Outputs:

- Prioritized GitHub inbox summary
- Recommended next actions
- Commands for follow-up inspection

Creates/Modifies:

- None in report mode
- May label, comment, assign, close, or move items only after approval

External Side Effects:

- Reads GitHub issues, PRs, reviews, checks, and project membership
- Writes GitHub issue/PR/project state only after approval

Confirmation Required:

- Before editing labels, assignees, comments, project fields, or issue state
- Before rerunning workflows
- Before merging or closing anything

Delegates To:

- `github-fix-ci` for failing PR checks
- `github-address-comments` for existing review comments
- `github-review-suggestions` when a PR needs inline review feedback
- `project-board` when the board configuration needs inspection
- `board-sync` when existing item values or delivery evidence need reconciliation

## Workflow

Resolve `<skill-dir>` to this skill's installed directory through the active
catalog before running a helper. Do not assume a repository checkout or a
provider-specific environment variable.

1. Verify auth:

   ```bash
   gh auth status -h github.com
   gh api user --jq .login
   ```

2. Generate the inbox:

   ```bash
   node <skill-dir>/scripts/github-inbox-report.mjs
   ```

   Common filters:

   ```bash
   node <skill-dir>/scripts/github-inbox-report.mjs --owner shipshitdev
   node <skill-dir>/scripts/github-inbox-report.mjs --repo shipshitdev/shipcode
   node <skill-dir>/scripts/github-inbox-report.mjs --project shipshitdev/1
   node <skill-dir>/scripts/github-inbox-report.mjs --limit 50
   ```

3. Triage order:
   - Review requests
   - Authored PRs with failing checks
   - Assigned P0/P1 or blocking issues
   - Mentions needing a response
   - Stale assigned issues
   - Project-board items missing status or priority

4. For each item, choose one next action:
   - Inspect
   - Fix
   - Reply
   - Defer
   - Reassign
   - Close

5. Ask before applying any writes. When writing, use the smallest command:

   ```bash
   gh issue edit <number> --add-label "priority:P1"
   gh issue comment <number> --body-file <file>
   gh pr review <number> --comment --body-file <file>
   ```

## Rules

- Prefer a short queue over a complete dump.
- Keep review requests above authored work unless production is blocked.
- Treat failing checks as actionable only after reading the failure.
- Do not close or defer user-facing issues without leaving a reason.
- If GitHub search results are noisy, narrow by `--repo`, `--owner`, or `--project` before making recommendations.