GitHub Issue Resolver

GitHub Issue Resolver

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: Load guardrails.json config Validate scope (repo, branch, path) Check action gate (auto/notify/approve) Validate command against allowlist 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

Phase 1 — Issue Discovery

Trigger: User provides a GitHub repository (owner/repo). Steps: Validate repo against guardrails: python3 scripts/guardrails.py repo <owner> <repo> If blocked, tell the user and stop. 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:
• Lock the issue (one-at-a-time enforcement):
• python3 scripts/guardrails.py issue_lock <owner> <repo> <issue_number>
• Read full issue thread including comments.
• Clone the repo (Gate: notify):
• python3 scripts/sandbox.py run git clone https://github.com/<owner>/<repo>.git /tmp/openclaw-work/<repo>
• Create a safe branch (Gate: auto):
• python3 scripts/sandbox.py run git checkout -b fix-issue-<number>
• Explore codebase — read relevant files. For each file:
• python3 scripts/guardrails.py path <file_path>
• 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.
• 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: Find and run tests (Gate: notify): python3 scripts/sandbox.py run npm test # or pytest, cargo test, etc. If tests fail AND autoRollbackOnTestFail is true: Revert all changes Notify user Suggest alternative approach If no tests exist, write basic tests covering the fix. 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.
• Commit changes (Gate: approve):
• python3 scripts/sandbox.py run git add .
• python3 scripts/sandbox.py run git commit -m "Fix #<number>: <title>"
• 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 ✅
• Ask explicitly: "Ready to push and create a draft PR?"
• 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).
• Share the PR link — user reviews on GitHub.
• Unlock the issue:
• python3 scripts/guardrails.py issue_unlock

Scripts Reference

ScriptPurposeRun Without Readingscripts/recommend.pyPrimary entry point — fetch, score, and present issues✅scripts/fetch_issues.pyRaw issue fetcher (used internally by recommend.py)✅scripts/analyze_issue.pyDeep analysis of single issue✅scripts/create_pr.pyPR creation wrapper✅scripts/guardrails.pyGuardrail enforcement engine✅scripts/sandbox.pySafe command execution wrapper✅scripts/audit.pyAction logger✅

References

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