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:

   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.