store: Issue Worker Agent: Phased Workflow Architecture

graph/decisions/issue-worker-agent-phased-workflow-architecture-45c219.md

@@ -0,0 +1,55 @@
+---
+id: 45c21973-7fae-4cf7-b247-b40a757d54b0
+type: decision
+title: "Issue Worker Agent: Phased Workflow Architecture"
+tags: [claude-configs, issue-worker, agent-design, gitea, automation, workflow, cognitive-memory]
+importance: 0.7
+confidence: 0.8
+created: "2026-03-02T20:19:30.456720+00:00"
+updated: "2026-03-02T20:19:30.456720+00:00"
+---
+
+# Issue Worker Agent: Phased Workflow Architecture
+
+## Context
+Rewrote the issue-worker agent at `~/.claude/agents/issue-worker.md` from a flat 10-step workflow into 4 distinct phases. Config synced to Gitea at commit `a62f16d`.
+
+## Architecture
+
+### Phase 1: Understand
+- Read issue from Gitea
+- Explicitly read `CLAUDE.md` before any code work
+- Assess feasibility
+- Add `status/in-progress` label to issue
+
+### Phase 2: Implement
+- Explore relevant code
+- Create branch using `-B` flag for retry safety
+- Implement fix
+- Run tests with auto-discovery: `CLAUDE.md` → `Makefile` → `pyproject.toml` → `package.json` → `Cargo.toml`
+
+### Phase 3: Review & Ship
+- Self-review via `git diff` before committing (avoids needing a second cleanup commit)
+- Commit and push
+- Create PR via `gitea-mcp`
+- Swap labels: remove `status/in-progress`, add `status/pr-open`
+- Comment on original issue with PR link
+
+### Phase 4: Remember
+- Store cognitive memory of fix with proper tags
+- Create graph edges to related memories using `memory_relate`
+
+## Key Decisions
+
+### Branch Naming
+- Changed from `ai/<repo>#<issue_number>` to `ai/<repo>-<issue_number>`
+- Reason: `#` causes shell interpretation issues and URL encoding problems
+
+### MCP Tools Added
+- `edit_issue` — for swapping labels during phase transitions
+- `memory_search` — for finding related existing memories in Phase 4
+- `memory_relate` — for creating graph edges in Phase 4
+
+### Self-Review Placement
+- `git diff` review placed before commit, not after
+- Avoids needing a follow-up fixup commit for issues caught post-commit