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:

```bash

python3 scripts/guardrails.py repo

```

If blocked, tell the user and stop.

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

```bash

python3 scripts/recommend.py

```

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 --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):

```bash

python3 scripts/guardrails.py issue_lock

```

1. Read full issue thread including comments.

1. Clone the repo (Gate: notify):

```bash

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

```

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

```bash

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

```

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

```bash

python3 scripts/guardrails.py path

```

1. 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.

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

Phase 3 — Testing

After implementing:

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

```bash

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

```

1. If tests fail AND autoRollbackOnTestFail is true:
• Revert all changes
• Notify user
• 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):

```bash

python3 scripts/sandbox.py run git add .

python3 scripts/sandbox.py run git commit -m "Fix #: