# GitHub Issue Loop — design walkthrough

This example shows one way to structure a real-world loop. It automates the full lifecycle of fixing a GitHub issue: fetch → research → implement → test → browser smoke → review → fix loop → push → PR.

No code needed — the focus here is on the **node design** and the **patterns** that make the loop robust.

## Node map (15 nodes)

```
prepare_issue → create_branch → research_fast → sanitize_research_context
→ implement → sanitize_implementation_context → run_tests → run_browser_smoke
→ implementation_report_gate → review_quality → sanitize_review_context
→ review_gate → implement_fix_from_review → final_summary → create_pr
```

## What each node does

### `prepare_issue` (code)
Fetches the GitHub issue via `gh` CLI. Also detects the project's package manager, test commands, and directory structure. All of this is deterministic — no LLM, no cost.

### `create_branch` (code)
Creates a clean git branch named after the issue. Deterministic. Fail-safe (aborts if branch already exists).

### `research_fast` (LLM)
A fast research agent with read-only tools. No write access, no implementation planning. Goal: gather codebase facts the implementation agent needs. Assigned a cheap/fast model with low thinking budget.

### `sanitize_research_context` (code)
Builds a clean text block from the research artifacts. This is what gets injected into the next LLM node — no raw tool-call logs, no chat history from the research node.

### `implement` (LLM)
The coding agent. Full read/write tools. Has a long timeout (15 min) because implementation takes real work. Includes a steering rule: if the agent makes too many edits without running validation, the loop nudges it to finish.

### `sanitize_implementation_context` (code)
Pulls together: issue summary, changed files, diff output, test results, browser smoke results. Produces a single clean context block for the reviewer.

### `run_tests` (code)
Runs whatever test commands were detected in `prepare_issue`. Reports pass/fail per test command. Pure shell — deterministic.

### `run_browser_smoke` (code)
Starts a dev server, runs Playwright against affected routes, and catches React runtime errors (like "Maximum update depth exceeded"). This is programmatic, not LLM-based, so it's fast and reliable.

### `implementation_report_gate` (code)
Validates that the implementation report is complete. Checks that the issue has a summary, files were actually changed, tests and browser smoke ran. If any of these are missing, the loop routes to the fix node instead of review.

### `review_quality` (LLM)
A read-only code review agent. Assigned a powerful model with high thinking budget. It produces a verdict: PASS or NEEDS_FIX, with a list of specific required fixes. Pragmatic — no style nitpicks, only real correctness/security/maintainability concerns.

### `sanitize_review_context` (code)
Extracts just the verdict and required fixes from the review artifacts. Cleans for the fix loop.

### `review_gate` (code)
Checks the verdict. PASS → final summary. NEEDS_FIX → routes to the fix node. Enforces a maximum of 2 review-fix cycles to prevent infinite loops.

### `implement_fix_from_review` (LLM)
A focused fix agent. It receives only the review findings and the implementation context. No broad re-research. Narrow scope, shorter timeout.

_(This node is also used when tests or browser smoke fail — the loop routes back here automatically.)_

### `final_summary` (code)
Builds a structured summary from all artifacts: issue, implementation, tests, browser smoke, review, PR URL. Deterministic.

### `create_pr` (code)
Commits all changes, pushes the branch, and creates a GitHub PR via `gh pr create`. Fully automatic — no approval gate.

## Key design patterns

**Deterministic gates, not LLM gates.**  
Validation (report quality, review verdict, test pass/fail) happens in code nodes. LLM nodes only produce content — the loop owns the decisions.

**Sanitize between every LLM node.**  
After research → sanitize, after implementation → sanitize, after review → sanitize. This prevents context bloat from tool calls in previous nodes.

**Model routing by node responsibility.**  
- Research → cheap/fast model (low thinking)
- Implementation → capable coding model (low thinking)
- Review → powerful analytical model (high thinking)

**Bounded fix loop.**  
The review gate allows at most 2 cycles of review → fix → review. After that, the loop completes or fails regardless. No infinite loops.

**Programmatic browser smoke.**  
Runtime errors are caught by Playwright, not by an LLM looking at screenshots. Faster, cheaper, more reliable.

**Automatic PR creation.**  
The final code node commits and pushes. No human approval step — the loop was designed for full automation.

---

See `definition.ts` and `handlers.ts` in this directory for the full implementation.