/implement-issue

Implement Issue Workflow

You are orchestrating a Plan → Implement → Review → Remediate → PR cycle for a GitHub issue, with support for stacked PRs when issues form a linear dependency chain.

Input

The user will provide a GitHub issue number: $ARGUMENTS

Phase 1: Load Context & Determine Stacking

1. Run the context loader script to fetch all issue data in one shot:

   .claude/scripts/load-issue-context.sh <number>

This fetches: issue details, all comments, milestone issues, dependency states, open feat/ PRs, and git state. 2. Read CLAUDE.md and MEMORY.md for project conventions 3. From the script output, verify all dependencies are complete (closed/merged or open PR in current stack)

Stacking Decision

Determine whether this issue should **stack** on a previous branch or **start fresh from main**.

**Algorithm:** 1. Find this issue's position in any implementation sequence 2. Look at the **previous issue** in the sequence (by step number, not by dependency list) 3. If the previous issue has an **unmerged PR branch** that is an ancestor of this issue's dependencies → **stack on that branch** 4. If the previous issue is already **merged to main** → **branch from main** 5. If this issue has **multiple unmerged predecessors on different branches** → this is a **merge point**. STOP and tell the user the predecessor PRs must be merged first.

**In practice:** The script output includes an `=== Open Feature Branches ===` section listing all open PRs on feat/ branches and their targets. Use this to determine stacking:

# If stacking:
git checkout <predecessor-branch>
git checkout -b feat/<this-issue>

# If fresh from main (works in worktrees where local main may not exist):
git fetch origin main
git checkout -b feat/<this-issue> origin/main

Report the stacking decision to the user:

Stacking: feat/<this-issue> → feat/<predecessor-issue> → ... → main
PR will target: feat/<predecessor-issue>

or:

Fresh branch: feat/<this-issue> from main
PR will target: main

**IMPORTANT:** Record the stacking decision (base branch and PR target) — this information must be included in the plan so it survives context compression.

Phase 2: Plan

1. Enter plan mode with `EnterPlanMode` 2. Explore the codebase areas relevant to the issue using Grep/Glob and the Agent tool with Explore subagent 3. Design the implementation approach:

• Which files to create/modify
• What types, traits, functions to add
• How it integrates with existing code
• What tests to write (TDD — tests first)

Plan Content Requirements

The plan must be **self-contained** — Claude Code's plan mode keeps the plan file fully loaded after context compression, so the plan becomes the primary reference for all subsequent phases. Include ALL of the following sections:

Section 1: Branch & Stacking

## Branch Strategy
- **Branch name:** `feat/<number>-<short-description>`
- **Base branch:** `main` | `feat/<predecessor-branch>`
- **PR target:** `main` | `feat/<predecessor-branch>`
- **Create command:** `git checkout <base> && git pull && git checkout -b feat/<branch-name>`

Section 2: Implementation Plan

The actual code changes — files, types, functions, integration points, estimated line counts, file size compliance checks.

**File size compliance:** For each file being created or modified, note:

• Current line count (for modified files)
• Estimated final line count
• Whether it stays under 500 (soft limit, CI warns) / 700 (hard limit, CI fails)

Section 3: Implementation Order

Numbered steps for the implementation, including: 1. Create the branch (with exact command from Section 1) 2. Implementation steps (code changes) 3. Quality gate steps

Section 4: Post-Implementation Checklist

This section ensures nothing is forgotten after the plan is accepted. Include it verbatim:

## Post-Implementation Checklist

### Quality Gate (run all, fix any failures before review)
- [ ] `cargo fmt -- --check`
- [ ] `cargo clippy --workspace --all-targets -- -D warnings`
- [ ] `cargo test`
- [ ] `tokf verify` (if filter changes were made)

### Multi-Agent Review (4 parallel agents)
Launch 4 review agents in parallel using the Agent tool:
1. **Acceptance Criteria** — verify each criterion from the issue with PASS/FAIL
2. **Code Quality** — file/function size limits, duplication, naming, error handling
3. **Architecture** — module structure, API design, pattern consistency, downstream impact
4. **Test Coverage** — public API coverage, edge cases, meaningful assertions

Provide each agent with:
- The issue description and acceptance criteria
- The diff command: `git diff <base-branch>...HEAD`

### Remediation
- Fix all MAJOR findings, re-run quality gate
- Present MINOR findings to user for decision

### PR Creation
- Push: `git push -u origin <branch-name>`
- Create PR: `gh pr create --base <pr-target> --title "..." --body "..."`
- PR body must include: `Closes #<number>`, summary, test plan
- If stacked: include Stack section in PR body
- Wait for CI to pass (`gh pr checks <number> --watch`), fix failures if any
- Report PR URL and next issue in sequence (if any)

5. Write the plan using the plan mode tool (do NOT write to `.claude/plan.md` manually — the plan mode tool manages its own file that survives context compression) 6. Exit plan mode and wait for user approval

**STOP: Wait for user to approve the plan before proceeding.**

Phase 3: Implement

1. **Create the branch** per the Branch Strategy section of the approved plan 2. Create tasks for each implementation step using TaskCreate 3. Follow TDD:

• Write tests first
• Run tests to confirm they fail
• Implement the code
• Run tests to confirm they pass

4. Follow project standards (from CLAUDE.md):

• Files: soft limit 500 lines (CI warns), hard limit 700 lines (CI fails)
• Functions: under 60 lines (clippy.toml enforced)
• Conventional commits: `<type>(<scope>): <desc