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:

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:
2. ```bash
3. python3 scripts/guardrails.py repo <owner> <repo>
4. ```
5. If blocked, tell the user and stop.

1. Fetch, score, and present issues using the recommendation engine:
2. ```bash
3. python3 scripts/recommend.py <owner> <repo>
4. ```
5. 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): ```bash 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):
2. ```bash
3. python3 scripts/guardrails.py issue_lock <owner> <repo> <issue_number>
4. ```

1. Read full issue thread including comments.

1. Clone the repo (Gate: `notify`):
2. ```bash
3. python3 scripts/sandbox.py run git clone https://github.com/<owner>/<repo>.git /tmp/openclaw-work/<repo>
4. ```

1. Create a safe branch (Gate: `auto`):
2. ```bash
3. python3 scripts/sandbox.py run git checkout -b fix-issue-<number>
4. ```

1. Explore codebase — read relevant files. For each file:
2. ```bash
3. python3 scripts/guardrails.py path <file_path>
4. ```

1. Plan the fix — explain approach to user:
2. ```
3. ## Proposed Fix
4. - Problem: [root cause]
5. - Solution: [what changes]
6. - Files: [list of files and what changes in each]
7. - Estimated diff size: [lines]
8. ```

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

1. Implement the fix (Gate: `approve`):
2. - Apply changes
3. - Check diff size: `python3 scripts/guardrails.py diff <line_count>`
4. - Log: `python3 scripts/audit.py log_action write_code success`

---

Phase 3 — Testing

After implementing:

1. Find and run tests (Gate: `notify`):
2. ```bash
3. python3 scripts/sandbox.py run npm test # or pytest, cargo test, etc.
4. ```

1. If tests fail AND `autoRollbackOnTestFail` is true:
2. - Revert all changes
3. - Notify user
4. - Suggest alternative approach

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

1. 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`):
2. ```bash
3. python3 scripts/sandbox.py run git add .
4. python3 scripts/sandbox.py run git commit -m "Fix #<number>: <title>"
5. ```

1. Show a change summary (NOT the raw diff) — keep it concise:
2. ```
3. ## Changes
4. - src/models.py — Added field validation (title length, enum checks)
5. - app.py — Added validation to POST endpoint, 400 error responses
6. - tests/test_app.py — 22 new tests covering validation rules
7. - 4 files changed, ~100 lines of source + ~150 lines of tests
8. - All tests passing ✅
9. ```

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

1. Only after user says "yes" (Gate: `approve`):
2. ```bash
3. python3 scripts/sandbox.py run git push -u origin fix-issue-<number>
4. python3 scripts/sandbox.py run gh pr create --draft --title "..." --body "..."
5. ```
6. Note: PRs are always created as draft by default.
7. The PR body should include a detailed description of all changes, test results,
8. and link to the issue (Closes #N).

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

1. Unlock the issue:
2. ```bash
3. python3 scripts/guardrails.py issue_unlock
4. ```

---

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