Automated GitHub Issue Resolver — Harness Design

Problem Description

A developer tools company wants to build an agent that automatically resolves GitHub issues in open-source repositories. The product works as follows: a user connects their repository, selects an open issue, and the agent checks out the repo, analyzes the codebase, writes a code fix, verifies it against the existing test suite, and opens a pull request — all without human involvement during execution.

The typical issue takes 10-40 minutes for the agent to work through. Some complex issues (multi-file refactors or missing test coverage) can take 1-2 hours. The team has CI/CD infrastructure including test runners, linters, and type checkers. They have access to frontier models. Cost per resolved issue matters but quality is the primary concern — PRs that break tests or introduce regressions are worse than no PR at all.

The company has tried a basic single-loop prototype that produces inconsistent results: sometimes the agent declares success prematurely, sometimes it loops forever trying the same approach, and sometimes its edits corrupt files. They need a proper harness architecture to go into production.

Output Specification

Produce a comprehensive design document in Markdown saved as design.md. The document should cover every major architectural decision needed to take this system from prototype to production — from how many agents to use and what loop to run, through to how the system knows when it is genuinely done and how it recovers when things go wrong.

For each major decision in the document, include the rationale and note the conditions under which you would revisit the choice.

Also produce a brief decisions.md that lists, in a table, each key architectural decision and the single most important reason it was made.