# Address Your Own Review Feedback (Reviewer → Contributor)

You have just completed a pull-request review (typically via
`agdt-initiate-pull-request-review-workflow`) and **requested changes** on one or more files.
Now **transition from reviewer to contributor**: implement the changes you asked for, capture
any durable lessons, push, and then reply to and resolve every thread you opened.

Follow each phase in order. Do not skip the verification or the sequential-delegation rules.

---

## Tooling Priority

**Always prefer `agdt-*` commands** over raw git or raw API calls. They provide centralized
state, consistent formatting, background-task tracking, and dry-run safety.

| Operation | Azure DevOps | GitHub |
|-----------|--------------|--------|
| Reply to a thread/comment | `agdt-reply-to-pull-request-thread` (then `agdt-task-wait`; set `resolve_thread true` to reply + resolve) | `agdt-gh-reply-to-review-comments` |
| Resolve a thread | `agdt-resolve-thread` (then `agdt-task-wait`) | `agdt-gh-resolve-review-threads` |
| Stage + commit/amend + push | `agdt-git-save-work` (then `agdt-task-wait`) | `agdt-git-save-work` (then `agdt-task-wait`) |

> `agdt-git-save-work` stages, commits **or amends**, rebases onto `main`, and pushes
> (force-pushing automatically when amending) — all in one command. You do **not** need a
> separate force-push step.

---

## Phase 1 — Re-establish Context

1. Identify the pull request and the threads/comments **you** opened during the review.
2. Re-read each requested change together with the current code so you implement the right fix
   (the file may have moved on since you reviewed it).
3. Note the PR's diff scope — the set of files already changed by this PR.

---

## Phase 2 — Implement the Requested Changes

Make **every** change you requested, including minor or non-blocking ones when they genuinely
improve the quality of the change set. Be a thorough contributor, not a minimal one.

Guardrails:

- **Scope guard** — only edit files already in this PR's diff. Do not refactor unrelated code or
  expand the PR's surface area.
- **Understand before editing** — read the surrounding function, class, or module first.
- **Preserve intent** — your fixes must keep the PR's original goal intact.

---

## Phase 3 — Capture Durable Lessons (Documentation)

If your review surfaced a lesson that would help a **class** of future changes (not a one-off
detail), record it so it is not re-learned every time. **Only document generalizable lessons —
do not bloat the docs with trivia.** Only **add** to documentation homes — never delete or
overwrite existing instruction files.

### Documentation homes

Choose the most appropriate home, using GitHub's
[repository custom-instruction mechanisms](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions):

- **Repository-wide** → `.github/copilot-instructions.md` (applies to every Copilot request in the repo).
- **Path / area-specific** → a path-specific instructions file under `.github/instructions/` named
  `NAME.instructions.md`, with YAML frontmatter `applyTo:` set to one or more comma-separated globs
  (e.g. `applyTo: "agentic_devtools/cli/**/*.py"`). These **stack on top of** the repo-wide file and
  are read by **both Copilot code review and the cloud agent**; add `excludeAgent: "code-review"` or
  `excludeAgent: "cloud-agent"` to scope to one consumer.
- **Agent-facing** → the nearest `AGENTS.md` in the directory tree (nearest wins), or a root
  `CLAUDE.md` / `GEMINI.md`.

### A. For future implementing agents

These are agents started via `agdt-initiate-work-on-jira-issue-workflow`. Add concise guidance to
the **most specific** home that applies:

- a path-specific `.github/instructions/NAME.instructions.md` whose `applyTo` glob matches the code, or
- the nearest `copilot-instructions.md` / `AGENTS.md` (closest to the code in question), or
- a shared conventions doc such as `docs/development/code-change-guidance.md` or
  `docs/development/codebase-conventions.md` — create one only if a shared home is genuinely
  warranted and none already fits.

### B. For future reviewing agents

These are agents started via `agdt-initiate-pull-request-review-workflow` (and GitHub Copilot code
review). Record the lesson where reviewers will see it next time:

- Append it to the repo's **review focus-areas** file — resolve the path from
  `.github/agdt-config.json` → `review.focus-areas-file`. If that key is not configured, prefer adding
  and configuring a repo-local focus areas file (for example `.github/review-focus-areas.md`).
- And/or add a path-specific `.github/instructions/NAME.instructions.md` whose `applyTo` glob matches
  the relevant code — **Copilot code review reads these from the PR base branch**.
- You may also reinforce the concept in the most specific doc that applies.

---

## Phase 4 — Save Your Work

1. Stage, amend, rebase, and push in one step:

   ```bash
   agdt-git-save-work
   agdt-task-wait
   ```

   This amends the existing single commit (keeping the PR at one commit), rebases onto `main`,
   and force-pushes. Update the commit message if the scope changed
   (`--overwrite-commit-message-title "..."` for the title; edit `commit-body.md` for the body).

2. **Push-fix-push loop** — if a pre-push hook rejects the push, read `.pre-push-output.log`
   (and `check-output-condensed.txt` if present), fix the issues, and re-run `agdt-git-save-work`.
   Never bypass with `--no-verify`. See `.github/instructions/pre-push-hook.instructions.md`.

3. **Verify the push landed** — confirm the remote head SHA now matches your local commit
   **before** you reply that a thread was `addressed in <short-sha>`:

   ```bash
   agdt-gh-pr-state --pr {pr_number} --repo {owner}/{repo}   # GitHub: compare github.head_ref_oid to your local SHA
   git rev-parse HEAD
   ```

   On Azure DevOps, confirm the PR's latest commit matches your local `HEAD`.

---

## Phase 5 — Reply to and Resolve Every Unresolved Thread

For **each** unresolved thread/comment, post a reply explaining how it was addressed, then
resolve it:

- For implemented changes, reference the commit (e.g. `addressed in <short-sha>`).
- For anything you deliberately did **not** change, explain why.

Use the provider's `agdt-*` reply/resolve commands from the Tooling Priority table. On Azure
DevOps you can reply and resolve in one call by setting `resolve_thread true`.

On GitHub, the actionable unit is the review thread anchored at the **parent** review comment.
Reply to and resolve the parent comment's thread; treat reply comments as context, not as separate
targets.

> **⚠️ CRITICAL — Delegate reply/resolve work SEQUENTIALLY, never in parallel.**
>
> If you hand the reply/resolve work to subagents, run them **strictly one at a time** — each
> subagent must fully complete before the next one starts. **Never run them in parallel.**
>
> All `agdt-*` commands share a single per-worktree `state.json`. Parallel subagents each call
> `agdt-set thread_id ...` / `agdt-set content ...` concurrently and **overwrite each other's
> state**, which posts replies to the wrong threads or drops them entirely. The safest approach is
> to **do the replies yourself in a sequential loop** rather than delegating them at all.

---

## Phase 6 — Recap

Give a structured recap:

- A table of each thread: id, file, what was requested, how it was addressed, commit.
- The docs you updated, and why each lesson was generalizable enough to record.
- The final commit SHA and the PR link.
- Anything left for a human to handle.
