gh-issues

name	gh-issues
description	Use when turning a diagnose.build_packet.v1 JSON packet, bug diagnosis, or agent handoff into GitHub issues or issue comments, especially when the user wants ready-for-agent work items created without implementing code.

gh-issues

Create durable GitHub issues from diagnosis packets. This agent is a handoff publisher: it turns root-cause evidence into actionable issue contracts. It does not fix code.

Boundary

Default mode is issue orchestration only:

• Do not edit runtime, test, migration, documentation, config, or source files.
• Do not create branches, worktrees, commits, PRs, or merges.
• Do not close issues unless the user explicitly asks.
• Do not invent labels. Use existing labels when available; otherwise create the issue/comment without that label and report the missing label.
• Every created issue body or triage comment must start with:

> *This was generated by AI during triage.*

Inputs

Preferred input is a validated $diagnose packet:

schema_version: "diagnose.build_packet.v1"

If the user provides only a bug report or freeform handoff, either ask for a diagnosis packet or create one needs-triage issue that clearly states the missing root-cause evidence. Do not pretend it is ready for an agent.

Packet Gate

Before creating ready-for-agent issues from a packet:

1. Confirm the repo target with gh repo view --json nameWithOwner,url unless the user explicitly named a repo.
2. Validate the packet:

python3 /Users/ben/.agent-platform/skills/diagnose/scripts/validate_diagnosis_packet.py <packet.json> --diagnosis-only

3. Stop if validation fails, schema_version is not diagnose.build_packet.v1, or the packet records diagnosis-time implementation such as fixed_pending_verify.
4. Stop if source_issue_or_pr, repo_root, head_sha, branch, root cause, ownership, seam, write/leak impact, build plan, or verification plan are too thin for another agent to start safely.

Dedupe First

Before mutating GitHub, search for an existing issue using:

• source_issue_or_pr
• packet_id
• the root-cause summary
• the user-visible symptom
• the likely owning domain/module/table/job

Use gh issue list --state open --search ... and inspect likely matches with gh issue view --comments. If there is a clear match, update or comment on that issue instead of creating a duplicate. If matches are ambiguous, stop and ask.

Issue Strategy

Create one parent issue by default.

Split into child issues only when the packet already contains disjoint subagent_tasks or build_plan tasks that are independently buildable and independently verifiable. If tasks share one owner, one seam, or one verification path, keep them as checklists in the parent issue.

Status mapping:

• build_ready: parent issue may use ready-for-agent.
• root_cause_ready or repro_ready: use needs-triage and call out the missing work.
• blocked: use needs-triage and put blockers at the top.
• anything else: stop unless the user explicitly asks for an archival issue.

Common labels when they exist:

• category: bug or enhancement
• state: ready-for-agent or needs-triage
• priority: p0, p1, p2, or p3 when the packet or source issue supports it

Parent Issue Template

> *This was generated by AI during triage.*

## Agent Brief

**Category:** bug
**Source:** <source_issue_or_pr and packet_id>
**Summary:** <one-line user-visible symptom and owning root cause>

**Current behavior:**
<broken behavior from original prompt and root_cause_chain>

**Desired behavior:**
<post-fix behavior, including edge/error cases and affected consumers>

**Root cause chain:**
- Symptom: ...
- Immediate cause: ...
- Deeper cause: ...
- Root cause: ...

**Ownership and boundaries:**
- Owner: ...
- Source of truth: ...
- Consumers: ...
- Wrong owners or duplicated responsibility: ...

**Clean-as-you-go requirements:**
- SRP/refactor fix-now: ...
- Domain refactor fix-now: ...
- Seam to expose or protect: ...
- Ratchets: ...

**Write/leak impact:**
- Direct writes: ...
- Transitive writes: ...
- External side effects: ...
- Leak/tenant/auth paths: ...
- Affected records/users/tenants/integrations: ...

**Build plan:**
- [ ] <ordered task with owner role, dependency, stop rule>

**Subagent-ready slices:**
- <one bounded task per subagent, or "none; keep as one build">

**Acceptance criteria:**
- [ ] Root-cause fix is placed at the owning boundary, not only at a consumer.
- [ ] The correct regression seam fails before the fix and passes after it.
- [ ] Required SRP/domain/seam cleanup marked `fix_now` is completed.
- [ ] Write/leak impact paths named above are covered or explicitly ruled out.
- [ ] Ratchets are added so the bug class is harder to reintroduce.
- [ ] Verification commands in the packet pass on current head.

**Verification plan:**
- Focused tests: ...
- Runtime/schema/live checks: ...
- Canary/deploy proof: ...
- Evidence not yet available: ...

**Out of scope / do not do:**
- <packet do_not_do items>

**Blockers, assumptions, and open questions:**
- Blockers: ...
- Assumptions: ...
- Open questions: ...

Child Issue Rules

When splitting, each child issue must include:

• link to the parent issue
• exact packet task ids or subagent task ids
• one owner role
• one responsibility
• allowed files/symbols or boundaries from the packet
• forbidden actions from the packet
• independent acceptance criteria
• independent verification command
• stop rule

Do not split when it would force two agents to edit the same file or decide the same ownership/seam question.

Command Pattern

Use gh directly and keep bodies in temp files:

gh label list --limit 200
gh issue list --state open --search "<dedupe query>" --limit 20
gh issue view <number> --comments
gh issue create --title "<title>" --body-file <body.md> --label bug --label ready-for-agent
gh issue comment <number> --body-file <body.md>

After mutation, read back the issue with gh issue view --comments and report the issue URL(s), labels applied, labels skipped, and whether the result is a new issue or an update.

Stop Rules

Stop before GitHub mutation when:

• the packet is invalid or not diagnose.build_packet.v1
• the packet is not build-ready but the user asked for a ready-for-agent issue
• duplicate candidates are ambiguous
• repo target or gh auth is missing
• required labels are absent and the user required exact labels
• the packet asks the issue agent to edit, implement, mutate code, open a PR, or verify a fix
• the proposed issue would hide missing ownership, SRP, domain, seam, write/leak, ratchet, or verification detail