Reduce PR Buildkite Detective comment spam with marker-based upsert

docs/workflows/gh-agent-workflows/estc-pr-buildkite-detective.md

@@ -52,9 +52,18 @@ if: >-
 - Proceeds only when failed script jobs are found, writes summaries/log tails under `/tmp/gh-aw/`, and analyzes those logs.
 - Performs deduplication against the latest prior detective comment; emits `noop` instead of a duplicate diagnosis.
 
+## Comment lifecycle
+
+The workflow keeps **at most one detective comment** per PR:
+
+- Every detective comment includes an invisible HTML marker: `<!-- gh-aw-detective: estc-pr-buildkite-detective -->`.
+- On each run the agent searches PR comments for this marker to find the existing detective comment.
+- **Same diagnosis**: the agent emits `noop`; the existing comment is left untouched.
+- **New diagnosis**: the agent calls `add_comment` with `reply_to_id` set to the existing comment's ID, updating it in place. If no prior comment exists, a new one is created.
+
 ## Safe outputs
 
-- `add-comment` — post a PR comment with root cause and remediation (max 1, older detective comments hidden)
+- `add-comment` — post or update a PR comment with root cause and remediation (max 1 per run; uses `reply_to_id` to update existing detective comment in place)
 - `noop` — emitted when:
   - the agent starts but Buildkite failure data is unavailable, or
   - diagnosis is unchanged from the most recent detective report

gh-agent-workflows/estc-pr-buildkite-detective/README.md

@@ -37,7 +37,14 @@ See [example.yml](example.yml) for the full workflow file.
 
 ## Safe Outputs
 
-- `add-comment` — post a comment explaining the failure (max 1, hides older detective comments)
+- `add-comment` — post a comment explaining the failure (max 1 per run); uses `reply_to_id` to update the existing detective comment in place when one is found
 - `noop` — emitted when diagnosis is unchanged since the last report
 
 If the agent starts but the pre-fetched Buildkite summary is unavailable, it emits `noop` (`No Buildkite failure data`). If no failed script jobs are found (or the build is not a PR build / not in a failed state), the workflow exits early with a notice and does not emit `noop`.
+
+## Comment Lifecycle
+
+The workflow keeps **at most one detective comment** per PR:
+
+- **Same diagnosis**: the agent emits `noop` and the existing comment is left untouched.
+- **New diagnosis**: the agent finds the existing detective comment (identified by the `<!-- gh-aw-detective: estc-pr-buildkite-detective -->` marker) and updates it in place via `reply_to_id`. If no previous comment exists, a new one is created.