GitHub Issue Resolver

Autonomous GitHub Issue Resolver Agent with guardrails. Use when the user wants to discover, analyze, and fix open issues in GitHub repositories. Triggers on...

Security Scan

The skill's files, scripts, and declared behavior are consistent with an autonomous GitHub issue-fixing agent that enforces guardrails; it does not request unrelated credentials or perform obvious hidden exfiltration, but it will execute shell/git/gh commands in your environment and write audit/state files locally so review and caution are advised before running on sensitive repos.

Purpose & Capability

The skill claims to discover, analyze, and fix GitHub issues and the provided scripts implement fetching, analysis, sandboxed command execution, guardrail checks, audit logging, and PR creation. No unrelated credentials or network hosts are requested; the pieces (recommend, fetch, analyze, sandbox, create_pr, guardrails, audit) align with the stated purpose.

Instruction Scope

SKILL.md confines actions to repository discovery, cloning, code edits, testing, and PR creation and enforces user approval for destructive actions. Runtime instructions reference only the provided scripts and standard developer tools; the agent will read/write repository files, call the GitHub API (via scripts), and run git/gh/ tests as documented. The guardrails explicitly forbid editing secrets, protected branches, and certain paths.

Install Mechanism

No install spec is provided (instruction-only plus included scripts), so nothing is downloaded or installed by the registry. The code runs with system binaries (git, gh, python, npm, pytest, etc.) that must already be present — consistent with the skill's purpose.

Credentials

The skill declares no required environment variables or credentials. It relies on the local environment's git/gh authentication if pushing/creating PRs (create_pr.py checks gh auth). That is proportionate to a tool that pushes code and creates PRs — no unrelated secrets are requested. Be aware that audit logs and state files will be written to disk and may include contextual data (filenames, diffs).

Persistence & Privilege

always:false (normal) and model invocation is enabled (normal). The skill persists state and audit logs under the skill/repo directory (writes .guardrails-state.json and audit/ session files). This is expected for an audit/logging feature but means local disk will be written to; review retention settings and where logs are stored before use.

Assessment

This skill appears internally consistent with its purpose, but take these precautions before installing or running it: - Review and test on a non-production repository first. The agent will clone repos, run shell commands, and can push/ create PRs if you approve. - Ensure you understand and control local git/gh authentication: create_pr.py uses the GitHub CLI and will push using your configured credentials if you approve a push. If you don't want pushes, do not approve git_push/create_pr gates. - Logs and state are written to the skill directory (audit/ and .guardrails-state.json). These may include diffs and contextual data — check retention and remove any sensitive artifacts. - The scripts execute shell commands via subprocess with shell=True; the guardrails attempt to sanitize and block dangerous commands, but avoid passing untrusted inputs to the skill and examine the guardrails config if you plan to run on sensitive projects. - If you require stricter control, populate guardrails.json allowlists (repos) and review command allow/block lists before use. If you want, I can: 1) point out any exact lines in the scripts that would run commands that need your auth, 2) search for any network endpoints beyond api.github.com, or 3) summarize the guardrail rules that would block modification of sensitive files.

Autonomous agent for discovering, analyzing, and fixing open GitHub issues — with a 5-layer guardrail system.

⚠️ GUARDRAILS — Read First

Every action goes through guardrails. Before any operation:

1. Load guardrails.json config
2. Validate scope (repo, branch, path)
3. Check action gate (auto/notify/approve)
4. Validate command against allowlist
5. Log to audit trail

For guardrail details, see references/guardrails-guide.md.

Key Rules (Non-Negotiable)

• Never touch protected branches (main, master, production)
• Never modify .env, secrets, CI configs, credentials
• Never force push
• Never modify dependency files without explicit approval
• Never modify own skill/plugin files
• One issue at a time — finish or abandon before starting new
• All dangerous actions require user approval (write code, commit, push, PR)
• Everything is logged to audit/ directory

---

Workflow

Phase 1 — Issue Discovery

Trigger: User provides a GitHub repository (owner/repo).

Steps:

1. Validate repo against guardrails:

   python3 scripts/guardrails.py repo <owner> <repo>
   

   If blocked, tell the user and stop.

2. Fetch, score, and present issues using the recommendation engine:

   python3 scripts/recommend.py <owner> <repo>
   

   This automatically fetches open issues, filters out PRs, scores them by severity/impact/effort/freshness, and presents a formatted recommendation.

   Always use recommend.py — never manually format issue output. The script ensures consistent presentation every time.

   For raw JSON (e.g., for further processing):

   python3 scripts/recommend.py <owner> <repo> --json
   

⏹️ STOP. Wait for user to select an issue.

---

Phase 2 — Fixing

Trigger: User selects an issue.

Steps:

1. Lock the issue (one-at-a-time enforcement):

   python3 scripts/guardrails.py issue_lock <owner> <repo> <issue_number>
   

2. Read full issue thread including comments.

3. Clone the repo (Gate: notify):

   python3 scripts/sandbox.py run git clone https://github.com/<owner>/<repo>.git /tmp/openclaw-work/<repo>
   

4. Create a safe branch (Gate: auto):

   python3 scripts/sandbox.py run git checkout -b fix-issue-<number>
   

5. Explore codebase — read relevant files. For each file:

   python3 scripts/guardrails.py path <file_path>
   

6. Plan the fix — explain approach to user:

   ## Proposed Fix
   - Problem: [root cause]
   - Solution: [what changes]
   - Files: [list of files and what changes in each]
   - Estimated diff size: [lines]
   

⏹️ STOP. Wait for user to approve the plan before implementing.

7. Implement the fix (Gate: approve):
   • Apply changes
   • Check diff size: python3 scripts/guardrails.py diff <line_count>
   • Log: python3 scripts/audit.py log_action write_code success

---

Phase 3 — Testing

After implementing:

1. Find and run tests (Gate: notify):

   python3 scripts/sandbox.py run npm test   # or pytest, cargo test, etc.
   

2. If tests fail AND autoRollbackOnTestFail is true:

   • Revert all changes
   • Notify user
   • Suggest alternative approach

3. If no tests exist, write basic tests covering the fix.

4. Report results to user.

---

Phase 4 — Draft PR for Review (Approval REQUIRED)

⚠️ NEVER create PR automatically. Always ask first.

Do NOT dump full diffs in chat. For any non-trivial project, push the branch and let the user review on GitHub where they get syntax highlighting, file-by-file navigation, and inline comments.

1. Commit changes (Gate: approve):

   python3 scripts/sandbox.py run git add .
   python3 scripts/sandbox.py run git commit -m "Fix #<number>: <title>"
   

2. Show a change summary (NOT the raw diff) — keep it concise:

   ## Changes
   - **src/models.py** — Added field validation (title length, enum checks)
   - **app.py** — Added validation to POST endpoint, 400 error responses
   - **tests/test_app.py** — 22 new tests covering validation rules
   - 4 files changed, ~100 lines of source + ~150 lines of tests
   - All tests passing ✅
   

3. Ask explicitly: "Ready to push and create a draft PR?"

4. Only after user says "yes" (Gate: approve):

   python3 scripts/sandbox.py run git push -u origin fix-issue-<number>
   python3 scripts/sandbox.py run gh pr create --draft --title "..." --body "..."
   

   Note: PRs are always created as draft by default. The PR body should include a detailed description of all changes, test results, and link to the issue (Closes #N).

5. Share the PR link — user reviews on GitHub.

6. Unlock the issue:

   python3 scripts/guardrails.py issue_unlock
   

---

Scripts Reference

Script	Purpose	Run Without Reading
scripts/recommend.py	Primary entry point — fetch, score, and present issues	✅
scripts/fetch_issues.py	Raw issue fetcher (used internally by recommend.py)	✅
scripts/analyze_issue.py	Deep analysis of single issue	✅
scripts/create_pr.py	PR creation wrapper	✅
scripts/guardrails.py	Guardrail enforcement engine	✅
scripts/sandbox.py	Safe command execution wrapper	✅
scripts/audit.py	Action logger	✅

References

• references/quick-reference.md — GitHub API reference, scoring rubric, test commands
• references/guardrails-guide.md — Full guardrails documentation and customization