managing-github-issues git:20261024.3106a82A

Immutable. This exact content never changes and is served at /api/v1/blob/40daa7fbaad235e7.

---
name: managing-github-issues
plugin: dev-utils
description: >
  Logs, promotes, ranks, synthesizes and audits GitHub issues with dry-run-first,
  deduplicated, taxonomy-validated and secret-redacted payloads. Use to log repository
  friction, bugs or map debt as issues, promote a local tasks/*.md note to an issue,
  rank issues P0-P3, draft a systemic refactoring proposal from friction clusters, or
  audit whether closed issues were genuinely resolved. Not for worktrees or the
  issue-to-PR flow (use resolving-github-issues).
allowed-tools: Bash, Read, Write
---

# Managing GitHub Issues (`managing-github-issues`)

One skill for the issue record itself: create, promote, rank, propose and audit.

## Contents

- [Constraints](#constraints) • [Quick Start](#quick-start) • [Modes](#modes) • [Workflow](#workflow) • [Verification](#verification) • [References](#references)

## Constraints

- **Dry-run first**: every mutating script previews its payload; pass `--execute` only after review.
- **Redaction and taxonomy gates**: `redaction_gate.py` blocks secrets; labels need `type:*`, `tier:*`, `source:*`, `risk:*` and `area:*` or `plugin:*`.
- **Body sections**: `## Summary`, `## Observed Behavior`, `## Expected Behavior`, `## Evidence`, `## Impact`.
- **Human gates**: `propose-refactor` never creates branches, commits or PRs; `review-resolution` is read-only and never reopens or relabels.
- **Ledger**: friction history lives in the repository's `map-debt.md` (repository root, references folder).

## Quick Start

```bash
python3 scripts/gh_issue_search.py --title "Bug summary" --area-label "area:dev-utils"
python3 scripts/gh_issue_create.py --title "Bug summary" --body "<5 sections>" --labels "type:friction,tier:1-friction,source:agent,risk:low,area:dev-utils"
```

## Modes

| Mode | Script | Use for | Reference |
|---|---|---|---|
| `log` | `gh_issue_search.py`, `gh_issue_create.py`, `gh_issue_comment.py`, `gh_issue_close.py` | Friction, bugs, map debt; dedupe into existing issues | [log.md](references/log.md) |
| `backlog` | `task_to_issue_bridge.py` | Promote a local `tasks/*.md` note to an issue | [backlog.md](references/backlog.md) |
| `prioritize` | `gh_issue_prioritize.py` | Rank P0-P3 and sync Projects v2 fields | [prioritize.md](references/prioritize.md) |
| `propose-refactor` | `friction_cluster_agent.py` (input) | One systemic proposal per Tier 3 root cause | [propose-refactor.md](references/propose-refactor.md) |
| `review-resolution` | `gh issue list` (read-only) | Audit `resolution:fixed` / `resolution:superseded` issues | [review-resolution.md](references/review-resolution.md) |

## Workflow

1. Pick the mode from the table and read its reference before running anything.
2. Search for existing issues first; comment on a matching root cause instead of creating a duplicate.
3. Run the mode's script in dry-run, check redaction and taxonomy, then rerun with `--execute` when authorized.
4. On any failure follow that mode's section in [fallback-tree.md](references/fallback-tree.md).

## Verification

```bash
python3 scripts/gh_issue_taxonomy_validate.py --labels "type:friction,tier:1-friction,source:agent,risk:low,area:dev-utils"
```

Check the mode's section in [acceptance-criteria.md](references/acceptance-criteria.md).

## References

- Modes: [log.md](references/log.md) • [backlog.md](references/backlog.md) • [prioritize.md](references/prioritize.md) • [propose-refactor.md](references/propose-refactor.md) • [review-resolution.md](references/review-resolution.md)
- Detail: [operation-catalog.md](references/operation-catalog.md) • [taxonomy-guide.md](references/taxonomy-guide.md) • [issue-taxonomy.md](references/issue-taxonomy.md) • [bridge-guide.md](references/bridge-guide.md) • [priority-matrix.md](references/priority-matrix.md)
- Gates: [acceptance-criteria.md](references/acceptance-criteria.md) • [fallback-tree.md](references/fallback-tree.md)