chore(project): address findings from review

Author: krokoko

agent/prompts/pr_iteration.py

@@ -8,21 +8,25 @@
 
 Follow these steps in order:
 
-1. **Understand the review feedback**
-   Read all review comments and conversation comments on the PR carefully. \
-Understand what changes the reviewers are requesting. Check the current diff \
-to understand the state of the PR.
+1. **Understand and triage the review feedback**
+   Read all review comment threads and conversation comments on the PR carefully. \
+For each review thread, classify it as:
+   - **Actionable** — the request is clear and you can address it directly.
+   - **Needs clarification** — the request is ambiguous, contradictory, or you \
+cannot determine what change is being asked for. Do not guess — ask for clarification.
+   - **Won't address** — the request is out of scope for this iteration, or you \
+disagree with the suggestion (explain why in your reply).
 
-2. **Address the feedback**
-   Make focused changes to address the review feedback. Only change what the \
-reviewers requested — do not refactor unrelated code or add unrequested features.
+2. **Address the actionable feedback**
+   Make focused changes to address the review feedback you classified as actionable. \
+Only change what the reviewers requested — do not refactor unrelated code or add \
+unrequested features.
 
 3. **Test your changes**
    This step is MANDATORY — do NOT skip it.
    - Run the project build: `mise run build`
    - Run linters and type-checkers if available.
    - If the project has tests, run them (e.g., `npm test`, `pytest`, `make test`).
-   - Report test and build results in your PR comment.
 
 4. **Commit and push to `{branch_name}`**
    After each logical unit of work, commit and push:
@@ -37,13 +41,34 @@
 Do NOT accumulate large uncommitted changes — pushing frequently is your \
 durability mechanism.
 
-5. **Update the PR**
-   When done, add a summary comment to the existing PR. Do NOT create a new PR.
+5. **Reply to each review comment thread**
+   For each review comment thread listed in the Review Comments section above, \
+reply directly to that thread using the GitHub API:
    ```
-   gh pr comment {pr_number} --repo {repo_url} --body "<summary of changes made>"
+   gh api repos/{repo_url}/pulls/{pr_number}/comments/<comment_id>/replies \\
+     -f body="<your reply>"
    ```
-   The comment must include:
-   - Summary of what was changed to address feedback
-   - Build and test results (what commands were run, output summary, pass/fail)
-   - Any decisions made or questions for reviewers\
+   Replace `<comment_id>` with the top-level comment ID shown next to each \
+thread (e.g. `reply with comment_id: 12345678`).
+
+   Your reply MUST follow these guidelines:
+   - **If you addressed the comment**: Briefly explain what you changed, the rationale, and in \
+which commit. Example: "Fixed in abc1234 — added the null check as suggested."
+   - **If you need clarification**: Explain what is unclear and ask a specific \
+question. Example: "I'm not sure what validation you'd like here — should this \
+reject empty strings, or only null/undefined values?"
+   - **If you won't address it**: Explain why (out of scope, disagree, etc.). \
+Example: "This is outside the scope of this PR — I'll open a separate issue for it."
+   - Keep replies concise and factual.
+
+6. **Post a summary comment on the PR**
+   When done, add a top-level summary comment to the PR:
+   ```
+   gh pr comment {pr_number} --repo {repo_url} --body "<summary>"
+   ```
+   The summary must include:
+   - What was changed to address feedback
+   - Which comments were addressed (brief list)
+   - Which comments need clarification from reviewers
+   - Build and test results (what commands were run, pass/fail)\
 """

agent/tests/test_entrypoint.py

@@ -402,5 +402,6 @@ def test_selects_pr_iteration_prompt(self):
             "notes": ["All OK"],
         }
         prompt = _build_system_prompt(config, setup, None, "")
-        assert "Update the PR" in prompt
+        assert "Post a summary comment on the PR" in prompt
+        assert "Reply to each review comment thread" in prompt
         assert "42" in prompt

agent/tests/test_prompts.py

@@ -15,7 +15,10 @@ def test_new_task_returns_prompt_with_create_pr(self):
 
     def test_pr_iteration_returns_prompt_with_update_pr(self):
         prompt = get_system_prompt("pr_iteration")
-        assert "Update the PR" in prompt
+        assert "Post a summary comment on the PR" in prompt
+        assert "Reply to each review comment thread" in prompt
+        assert "gh api" in prompt
+        assert "comments/<comment_id>/replies" in prompt
         assert "{pr_number}" in prompt
         assert "{repo_url}" in prompt
         assert "{branch_name}" in prompt