From a1d393f989a4d11bed0dd69fe6abcbd600f55fc0 Mon Sep 17 00:00:00 2001
From: Codex <noreply@openai.com>
Date: Wed, 6 May 2026 09:31:10 +0200
Subject: [PATCH] docs: prevent duplicate issue fix PRs

The issue triage and PR creation workflows did not require checking issue timeline cross-references for existing open PRs.

Added timeline checks to triage and create-pr instructions so agents skip duplicate PRs when an issue already has an associated fix.

Co-Authored-By: Codex <noreply@openai.com>

oreply@openai.com>
---
 .agents/skills/create-pr/SKILL.md    | 13 +++++++++++++
 .agents/skills/triage-issue/SKILL.md | 20 ++++++++++++++++----
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md
index 147316c4172..33ae4468e57 100644
--- a/.agents/skills/create-pr/SKILL.md
+++ b/.agents/skills/create-pr/SKILL.md
@@ -33,6 +33,19 @@ git push -u origin <branch-name>
 
 ## 3. Create the PR
 
+Before creating a PR for an issue, check whether that issue already has an open
+linked PR:
+
+```bash
+gh api repos/docker/docs/issues/<issue-number>/timeline --paginate \
+  --jq '.[] | select((.event=="cross-referenced" or .event=="connected" or .event=="referenced") and .source.issue.pull_request and .source.issue.state=="open") | {url: .source.issue.html_url, title: .source.issue.title}'
+```
+
+If this returns an open PR that addresses the same issue, stop. Don't open a
+duplicate PR; report the existing PR instead. Only proceed if there is no open
+linked PR, or if the existing PR clearly does not address the issue and you
+explain why in the new PR body.
+
 Derive the fork owner dynamically:
 
 ```bash
diff --git a/.agents/skills/triage-issue/SKILL.md b/.agents/skills/triage-issue/SKILL.md
index 70513da7841..c4fcf19bb85 100644
--- a/.agents/skills/triage-issue/SKILL.md
+++ b/.agents/skills/triage-issue/SKILL.md
@@ -28,9 +28,21 @@ Read the issue body and all comments. Identify:
 
 - What is the reported problem?
 - What content, URL, or file does it reference?
-- Are there linked PRs? Check whether they were merged or closed without merge.
 - Has anyone already proposed a fix or workaround in the comments?
 
+Check for linked PRs in the issue timeline, not only in the issue body or
+comments:
+
+```bash
+gh api repos/docker/docs/issues/$ARGUMENTS/timeline --paginate \
+  --jq '.[] | select(.event=="cross-referenced" or .event=="connected" or .event=="referenced") | {event, created_at, source: .source.issue.html_url, title: .source.issue.title, state: .source.issue.state}'
+```
+
+If an open PR already addresses the issue, don't open another PR. Review the
+existing PR instead, and report that the issue already has an associated PR. A
+merged PR is strong evidence the issue is fixed. A closed-without-merge PR means
+the issue is likely still open.
+
 ## 3. Follow URLs
 
 Find all `docs.docker.com` URLs in the issue body and comments. For each:
@@ -130,9 +142,9 @@ labels. Mention the action you took (closed, labeled, etc.).
 
 ## Notes
 
-- A merged PR linked to an issue is strong evidence the issue is fixed
-- A closed-without-merge PR means the issue is likely still open
+- Always check timeline cross-references before deciding to fix an issue
 - Do not narrate your process — produce the final report
 - End every issue comment with an accurate agent-disclosure footer that names
   the active coding agent, for example `Generated by Codex` or `Generated by
-  Claude Code`.
+Claude Code`.
+.