| name | github-issue-agent |
| plugin | dev-utils |
| description | Agent skill for safe, dry-run-first, deduplicated, root-cause-consolidated, evidence-validated, and secret-redacted logging of repository execution friction into GitHub Issues. USE ONLY for durable repository bugs, execution friction (T1-T3), map debt, and architectural improvements. DO NOT USE for temporary intra-session checklists (use task-agent instead).
|
| allowed_tools | ["run_command","view_file","write_to_file","replace_file_content","multi_replace_file_content","grep_search","list_dir"] |
GitHub Issue Agent (github-issue-agent)
Routing Directive: USE ONLY for durable repository bugs, execution friction (T1-T3), map debt, and architectural improvements. DO NOT USE for temporary intra-session checklists (use task-agent instead).
The github-issue-agent skill provides a safe, standardized interface for querying, searching, creating, commenting on, and validating GitHub Issues stemming from agent execution friction, map debt, bugs, and system improvements.
Dry-Run Default Execution Contract
[!IMPORTANT]
Safety First: By default, all issue-modifying operations (issue creation, commenting, label edits) execute in dry-run / payload-generation mode (execute=False).
No live mutation occurs unless execute=True is explicitly passed and all safety gates pass.
Before any GitHub issue is created or updated, the request passes through three mandatory security and quality gates:
- Secret Redaction Gate (
redaction_gate.py): Scans titles and bodies for tokens, API keys, private keys, or credentials. Blocks execution if detected.
- Taxonomy Validation Gate (
gh_issue_taxonomy_validate.py): Enforces issue-taxonomy.json constraints. Requires type:*, tier:*, source:*, risk:*, AND location (area:* OR plugin:*).
- Evidence Quality Body Validation Gate (
body_validator.py): Requires standard structured markdown sections (## Summary, ## Observed Behavior, ## Expected Behavior, ## Evidence, ## Impact).
Operation Catalog
1. create-friction-issue
Scaffolds and submits (or outputs payload for) a friction issue resulting from agent execution friction or tool failure.
- Helper Script:
plugins/dev-utils/skills/github-issue-agent/scripts/gh_issue_create.py
- Default Labels Required:
type:friction, tier:1-friction (or tier:2-structural / tier:3-architecture), source:agent, risk:low (or appropriate risk level), plus location (area:* or plugin:*).
- Input Parameters:
title: Short, clear summary of root-cause friction.body: Markdown content conforming to required sections.labels: List of taxonomy labels matching issue-taxonomy.json.execute: Boolean (False for dry-run payload generation, True for live creation via gh).
2. create-map-debt-issue
Converts an entry from map-debt.md into a formal tracked GitHub issue.
- Helper Script:
plugins/dev-utils/skills/github-issue-agent/scripts/gh_issue_create.py
- Default Labels Required:
type:map-debt, tier:*, source:agent, risk:*, location (area:* or plugin:*).
3. create-bug-issue
Logs a verified bug or code defect identified during execution or test failure.
- Helper Script:
plugins/dev-utils/skills/github-issue-agent/scripts/gh_issue_create.py
- Default Labels Required:
type:bug, tier:*, source:agent, risk:*, location (area:* or plugin:*).
4. search-related-issues
Searches open and closed issues for existing root-cause items to prevent duplicate issues.
- Helper Script:
plugins/dev-utils/skills/github-issue-agent/scripts/gh_issue_search.py
- Input Parameters:
title: Proposed issue title or keyword.area_label: Location label (area:* or plugin:*).file_paths: List of affected file paths.
- Output: Returns JSON object indicating if an existing root cause exists (
has_existing_root_cause), target issue number (target_issue_number), and action recommendation (comment_and_append_evidence vs create_new_issue).
5. comment-on-existing-issue
Appends additional empirical evidence, stack traces, or context to an existing issue rather than opening a duplicate.
- Helper Script:
plugins/dev-utils/skills/github-issue-agent/scripts/gh_issue_comment.py
- Input Parameters:
issue_number: GitHub issue ID.comment_body: Markdown comment text (must pass secret redaction scan).execute: Boolean (False for dry-run payload generation, True for live comment posting).
6. validate-issue-taxonomy
Validates a list of labels against issue-taxonomy.json.
- Helper Script:
plugins/dev-utils/skills/github-issue-agent/scripts/gh_issue_taxonomy_validate.py
- Usage: Run CLI or import
validate_taxonomy(labels: list[str]).
Taxonomy Reference
Taxonomy labels and rules are defined in plugins/dev-utils/skills/github-issue-agent/issue-taxonomy.json.
Mandatory dimensions for every issue:
type: type:bug, type:friction, type:map-debt, type:enhancement, type:documentation, type:security, type:architecture, type:test-gaptier: tier:0-quickfix, tier:1-friction, tier:2-structural, tier:3-architecturesource: source:agent, source:human, source:script, source:test, source:review, source:migrationrisk: risk:low, risk:medium, risk:high, risk:security-sensitive, risk:destructive-operationlocation: Must have at least one area:* label or one plugin:* label.
