teamcraft:address-review-issue

What this skill does

## Goal

Handle a round of PR review feedback — pull the comments, make the changes the developer approves, re-run the quality gates, and push. This skill is designed to be run as many times as needed through the review cycle. Each run addresses one round of feedback and pushes the result.

The work item status stays `in-review` throughout — that's accurate. The status only changes to `done` when `merge-issue` runs. This skill is about iterating on the PR, not advancing its state.

## Verify Branch State — Before Any File Modifications

This skill makes code changes and commits on the work branch the PR is built from. Before any file modifications, confirm the current branch is a work branch — not the default branch.

If the current branch IS the default branch (typically `main`), stop and tell the developer: "You're on the default branch, but this skill modifies the PR's work branch. Check out that branch and invoke me again." Do not auto-switch — the developer should know this skill isn't going to silently change their context.

If the current branch is a work branch, continue. Also confirm the work branch matches the PR you're about to address feedback on — if the branches don't match, ask the developer which is correct.

## Find the Work Item and PR

If the developer provides a work item ID, read it from `.teamcraft/work/`. If they don't, check `.teamcraft/work/INDEX.md` for a work item with `in-review` status that matches the current branch. Identify the PR associated with the current branch — use whatever GitHub/GitLab tools are available (the `gh` CLI, an MCP server, a browser-shared URL).

If no PR can be found, stop and tell the developer — this skill is for addressing feedback on an existing PR.

## Pull the Review Comments

Fetch all review comments on the PR — both inline comments on specific lines and top-level review comments. Group them by file if useful. Present the full set to the developer before making any changes.

For each comment, present:

- Which reviewer left it
- Where (file and line, or top-level)
- The comment text
- Your initial read on what the reviewer is asking for

Then ask the developer what to do: address it, discuss it first, or defer it. Do not assume. Reviewers sometimes ask for things that conflict with team conventions — the developer decides.

## Make the Changes

For each comment the developer approves for fixing:

- **Check for convention or decision conflicts first.** If the reviewer's suggestion touches an area that's likely covered by the team's captured conventions or technology decisions — branching, testing approach, commit format, architectural boundaries, data-layer choices, etc. — consult the relevant knowledge category BEFORE making the change. If there's a conflict (the reviewer suggests something the team's captured knowledge contradicts), surface it to the developer: "Reviewer suggests X; captured [convention/decision] says Y. Which wins here?" Let the developer decide. Don't silently resolve the conflict in either direction. When you raise such a conflict, also note whether the captured doc is Teamcraft-certified (see `../references/doc-provenance.md`): if it's UNVERIFIED, say so, since the "captured" rule you're weighing against the reviewer may be inherited or stale rather than a real team decision.
- Make the code change once any conflict is resolved.
- Run the full test suite — **all tests must pass, no exceptions**. Same rule as everywhere else: if tests fail, stop, investigate, fix. Never assume failures are unrelated.
- Commit the change with the work item ID in the commit message (e.g., `fix(feat-notification-prefs): address review feedback on validation logic`)

If the developer wants to reply to a review thread without making code changes (e.g., explaining why the current code is correct), help them draft the reply. Claude may or may not be able to post the reply directly depending on what GitHub/GitLab tools are available — if it can't, hand the text to the developer.

## Re-Run Quality Gates

After all approved changes are made, ask the developer which review agents to re-run — default to all three. The same agents from `validate-issue` apply:

- `teamcraft:code-health-reviewer`
- `teamcraft:security-reviewer`
- `teamcraft:acceptance-reviewer`

Invoke them via the Task tool in parallel with the base branch name in the prompt. Present findings the same way `validate-issue` does. If new findings come up, address them the same way (with developer approval, tests passing, commits with work item ID). Deferred findings still become work items — created inline to the **work-item standard** (`../references/work-item-standard.md`), drafted from the finding and shown for review, never handed back to the developer to run `create-issue` themselves.

## Push and Monitor CI

Only when all tests pass and all approved fixes are committed:

- Push the branch
- Monitor CI via the Monitor tool — **blocking**. This skill does not report success until CI passes.
- If CI fails: stop, report the failure, help address it. After re-push, monitor CI again.

## When the Skill Is Complete

The skill is complete when ALL of the following are true:

1. All review comments have been addressed (fixed, replied to, or explicitly deferred with the developer's acknowledgement and work items created)
2. All tests pass
3. The quality gates the developer chose to re-run have completed without blocking findings (or with deferrals captured as work items)
4. Changes are committed with work item IDs in commit messages
5. The branch is pushed
6. CI has completed successfully
7. The developer has explicitly confirmed they are satisfied with this round

Ask the developer: "Ready to hand this back to reviewers?" Wait for explicit confirmation.

Once confirmed, stop. Point them to:

- **If more rounds expected:** "When reviewers respond, run `/address-review-issue` again."
- **If the PR looks close to approval:** "Once the PR is approved, run `/merge-issue`."

Do NOT merge the PR here. Do NOT set the work item to `done` here. Those are `merge-issue`'s job.