Issue Ingest
Productivityissue-ingestIssue Ingest is an Agent Skill for productivity published in the ZaxbyHub/opencode-swarm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Full execution protocol for MODE: ISSUE_INGEST -- GitHub issue intake, localization, spec generation, and transition to the full fix workflow.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ZaxbyHub/opencode-swarm/blob/HEAD/.claude/skills/issue-ingest/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/issue-ingest, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Issue Ingest Protocol
This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
MODE: ISSUE_INGEST
Activates when: user invokes /swarm issue <url>; OR architect receives [MODE: ISSUE_INGEST issue="<url>"] signal.
Purpose: ingest a GitHub issue, localize root cause, and produce a resolution spec. The issue URL points to a GitHub issue that describes a bug, feature request, or task to be resolved.
Flags parsed from signal:
plan=true→ after spec generation, transition to MODE: PLAN (create implementation plan)trace=true→ after plan, delegate to swarm-implement skill for the fix workflow; the user invokes commit-pr to publish (implies plan=true)noRepro=true→ skip the reproduction step below
Phase 1: INTAKE
- Fetch the issue body using the GitHub CLI (
gh issue view <N> --repo <owner>/<repo> --json title,body,labels,assignees,comments) or web fetch.- If the issue cannot be fetched (404, private repo, no
ghauth, or the argument resolves to a PR not an issue), report the blocked operation explicitly and do not proceed on empty intake; fall back to any pasted issue text the user provided. Closed-issue cases proceed but note the closed state.
- If the issue cannot be fetched (404, private repo, no
- Parse the issue into a normalized Intake Note with four required fields:
- Observed behavior: what the issue reports
- Expected behavior: what should happen instead
- Reproduction steps: how to trigger the issue (may be absent; flag with
[NEEDS REPRO]if missing) - Environment: platform, version, configuration context
- If any required field is missing and cannot be inferred from context, flag as
[NEEDS REPRO]. - Attempt a minimal reproduction of the reported issue: record the exact commands and their output. Skip this step when
noRepro=true(set via--no-repro); in that case, note that reproduction was skipped and proceed on the issue text alone. - Ask the user clarifying questions one at a time, max 6 per intake, when the issue text is ambiguous; otherwise flag the item with markers like
[NEEDS REPRO]or[NEEDS CLARIFICATION]and proceed. - Exit when the Intake Note is complete or all missing fields are flagged.
Phase 2: LOCALIZATION
- Delegate to
the active swarm's explorer agentto scan the codebase for code areas related to the issue's observed behavior. - Build 2–5 candidate hypotheses for root cause, each with:
- Location: file(s) and function(s) most likely responsible
- Confidence: composite score (stack-trace match 0.4, recency 0.25, call-graph proximity 0.2, test-failure correlation 0.15)
- Falsifiability: a specific test or observation that would disprove this hypothesis
- Validate top-3 hypotheses in parallel using targeted
the active swarm's sme agentconsultations. - Prune to a single root cause hypothesis with supporting evidence.
- Exit when a root cause is identified with ≥70% confidence, or when all hypotheses are exhausted (report ambiguity).
Phase 3: SPEC GENERATION
- Include a Root Cause section derived from Phase 2 localization results: concise statement of the identified root cause, location, and confidence score; the
locationfield (file/function from Phase 2 localization) is the sole exception to the no-implementation-detail rule. Include a Fix Strategy section at product/behavior level (what the fix must accomplish, not how to implement it). - If
.swarm/spec.mdalready exists, route through MODE: SPECIFY step 1's classification (overwrite / refine / archive / non-shadowing check) before writing — do not clobber an existing spec. (This protects the drift-gate which consumes spec.md.) - Generate
.swarm/spec.mdusing the same SPEC CONTENT RULES as MODE: SPECIFY:- WHAT users need and WHY — never HOW to implement
- FR-### / SC-### numbering, Given/When/Then scenarios
- No technology stack, APIs, or code structure
[NEEDS CLARIFICATION]markers only for items that survive the clarification funnel: inventory all material uncertainties without numeric cap → classify each (self_resolved/critic_resolved/research_needed/user_decision/deferred_nonblocking) — Overconfidence guard: if the default is not directly supported by user request, spec, or recorded context, classify asuser_decisionrather thanself_resolved→ consult critic_sounding_board — critic responds per SoundingBoardVerdict: UNNECESSARY→DROP, RESOLVE→RESOLVE, REPHRASE→REPHRASE, APPROVED→ASK_USER — always-surface protection: always-surface categories must not receive UNNECESSARY/DROP; override to APPROVED/ASK_USER → record resolved items as assumptions → surface only survivors as markers with decision packet format (grouped by category, recommended defaults, blocking vs optional markers)- Important: Apply a fixed 5-minute protocol budget to
research_needed. If research does not complete within 5 minutes, automatically reclassify the item touser_decisionwith a note that research was incomplete, then surface it to the user.
- Cross-reference the spec against the issue's expected behavior to ensure alignment.
- If the issue is a bug: spec must describe the correct behavior, not the broken behavior.
- If the issue is a feature: spec must describe the user-facing outcome, not the implementation.
- Carry forward any
[NEEDS REPRO]/[NEEDS CLARIFICATION]flags from Phase 1 into the spec as open questions; do not silently drop them. - QA GATE SELECTION: Ask user which QA gates to enable (same dialogue as MODE: SPECIFY). Write to
.swarm/context.mdunder## Pending QA Gate Selection.
Phase 4: TRANSITION
Based on flags:
- No flags → report spec summary and suggest
PLANorCLARIFY-SPEC plan=true→ transition to MODE: PLAN using the generated spectrace=true→ transition to MODE: PLAN, then delegate to swarm-implement skill for the fix workflow; the user invokes commit-pr to publish
RULES:
- One question per message in INTAKE dialogue (max 6 questions)
- Hypotheses must be falsifiable — no unfalsifiable hypotheses
- Spec must be independently testable — each FR must have a verification path
- The issue URL is already sanitized by the issue command — do not re-sanitize