From 9ef87baedc81d4a7b198814f7b2bfd0478f79d96 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 2 Jun 2026 11:16:04 +0000
Subject: [PATCH] docs: document iterating on existing PRs in AI writeback

---
 guides/ai-agents/ai-writeback.mdx | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/guides/ai-agents/ai-writeback.mdx b/guides/ai-agents/ai-writeback.mdx
index 986e274f..470c38c1 100644
--- a/guides/ai-agents/ai-writeback.mdx
+++ b/guides/ai-agents/ai-writeback.mdx
@@ -82,6 +82,28 @@ Make the orders model better.
 
 When the pull request is ready, the agent posts the URL in the thread. Open it, review the diff, and merge as you would any other pull request. After merging, refresh dbt in Lightdash (or let your CI/CD do it) so the change takes effect.
 
+## Iterating on an existing pull request
+
+If you've already opened a writeback pull request — either earlier in the same thread or by pasting a link to one — the agent commits follow-up changes onto that PR's branch instead of opening a new one. The PR's title and description are refreshed to reflect the latest change.
+
+There are two ways this happens:
+
+- **Same thread.** If the thread already has a writeback PR, any further writeback requests in that thread automatically resume it. You don't need to paste the link.
+- **Paste a link.** In a new thread (or before a writeback PR exists for the current thread), paste the GitHub pull request URL alongside your request. The agent picks up the link, checks out that PR's branch, and commits your edits onto it.
+
+```text
+Update https://github.com/my-org/analytics/pull/482 so the `net_revenue`
+metric is rounded to 2 decimal places.
+```
+
+The pasted pull request must:
+
+- Live in the same GitHub repository as the project's dbt connection.
+- Be **open** — merged or closed PRs are rejected.
+- Have its branch in the same repository (PRs opened from forks are rejected).
+
+If any of those checks fail, the agent stops and tells you why instead of silently opening a new pull request.
+
 ## What happens if it can't run
 
 | Situation | Result |
@@ -90,6 +112,7 @@ When the pull request is ready, the agent posts the URL in the thread. Open it,
 | Project's dbt connection isn't GitHub | The agent tells you the project must be connected to GitHub for writeback. |
 | GitHub App isn't installed on the repo | The agent surfaces a setup error. Install the Lightdash GitHub App on the repository (from your project's dbt connection settings) and try again. |
 | Writeback agent makes no file changes | No pull request is opened. The agent reports back that nothing needed to change. |
+| Pasted PR link is in a different repo, merged, closed, or from a fork | The agent rejects the link with an explanation and does not open a new pull request. |
 
 ## Related