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](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 <owner> <repo>
   ```
   If blocked, tell the user and stop.

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

2. **Read full issue thread** including comments.

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

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

5. **Explore codebase** — read relevant files. For each file:
   ```bash
   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`):
   ```bash
   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`):
   ```bash
   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`):
   ```bash
   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:**
   ```bash
   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](references/quick-reference.md) — GitHub API reference, scoring rubric, test commands
- [references/guardrails-guide.md](references/guardrails-guide.md) — Full guardrails documentation and customization