From ccd617a8236e768a22a761b927e1ad7615573d10 Mon Sep 17 00:00:00 2001
From: Komal Vardhan Lolugu <67476199+KomalSrinivasan@users.noreply.github.com>
Date: Sat, 27 Jun 2026 04:08:35 +0530
Subject: [PATCH 1/3] create-implementation-plan: require unique identifiers
 (#1989)

The skill template tells the agent to use REQ-, TASK-, GOAL-, and
similar prefixed identifiers, but never says they have to be unique
or how to check. @basilevs reported plans coming back with duplicate
TASK IDs and proposed three POSIX one-liners that catch the two real
collision modes (table rows and bullet declarations) plus a broad
diagnostic scan.

Document the uniqueness rule under the existing Template Validation
Rules, then add a new "Identifier Uniqueness Check" section with all
three bash commands and instructions on which must come back empty
before the plan is finalized.

DEP-* references intentionally allowed in multiple sections per the
reporter's note.

Closes #1989.
---
 skills/create-implementation-plan/SKILL.md | 28 ++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/skills/create-implementation-plan/SKILL.md b/skills/create-implementation-plan/SKILL.md
index 08a91438b..bb64d622b 100644
--- a/skills/create-implementation-plan/SKILL.md
+++ b/skills/create-implementation-plan/SKILL.md
@@ -60,6 +60,34 @@ All implementation plans must strictly adhere to the following template. Each se
 - All identifier prefixes must follow the specified format
 - Tables must include all required columns
 - No placeholder text may remain in the final output
+- **Identifiers must be unique.** Every declaration of `REQ-NNN`, `SEC-NNN`, `CON-NNN`, `GUD-NNN`, `PAT-NNN`, `GOAL-NNN`, `TASK-NNN`, `ALT-NNN`, `DEP-NNN`, `FILE-NNN`, `TEST-NNN`, `RISK-NNN`, and `ASSUMPTION-NNN` must appear exactly once across the plan. `DEP-*` may appear in multiple sections (for example, Requirements and Dependencies) as a reference; that is not a declaration collision.
+
+## Identifier Uniqueness Check
+
+Run these checks before finalizing the plan. The first two must return zero rows. The third is informational.
+
+```bash
+# Set PLAN_FILE to the plan being validated.
+PLAN_FILE="/plan/<purpose>-<component>-<version>.md"
+
+# 1) Duplicate TASK / GOAL declarations in table rows.
+grep -oE '\| (TASK|GOAL)-[0-9]+ \|' "$PLAN_FILE" \
+  | sed -E 's/.*((TASK|GOAL)-[0-9]+).*/\1/' \
+  | sort | uniq -d
+
+# 2) Duplicate declaration IDs in bullet-style spec lines.
+grep -oE '^- \*\*(REQ|SEC|CON|GUD|RISK|ASSUMPTION|TASK|GOAL|FILE|TEST|PAT|ALT|DEP)-[0-9]+\*\*:' "$PLAN_FILE" \
+  | sed -E 's/^- \*\*([A-Z]+-[0-9]+)\*\*:.*/\1/' \
+  | sort | uniq -d
+
+# 3) Broad duplicate scan (diagnostic only; may include valid references).
+grep -oE '(REQ|SEC|CON|GUD|RISK|ASSUMPTION|TASK|GOAL|FILE|TEST|PAT|ALT|DEP)-[0-9]+' "$PLAN_FILE" \
+  | sort | uniq -d
+```
+
+Prerequisites: a POSIX-compatible shell (`sh` / `bash`) with `grep`, `sed`, `sort`, and `uniq`. On Windows without these tools, use equivalent platform-native commands and preserve the same declaration-vs-reference logic.
+
+If check (1) or (2) returns any row, re-number the duplicate so each identifier is declared exactly once, then re-run the checks until both are empty.
 
 ## Status
 

From 703974b9ef602cf191112228c5ebe8afb015b671 Mon Sep 17 00:00:00 2001
From: Komal Vardhan Lolugu <67476199+KomalSrinivasan@users.noreply.github.com>
Date: Sun, 28 Jun 2026 04:50:09 +0530
Subject: [PATCH 2/3] codespell: ignore GUD identifier prefix (#1989)

Upstream skills/create-implementation-plan/SKILL.md already uses
GUD-001 in the template body. Codespell currently slips past it on
word-boundary, but the regex alternation (GUD|RISK|...) added in the
previous commit on this branch makes codespell flag it as a misspelling
of GOOD.

GUD is the documented "Guideline" identifier prefix alongside REQ,
SEC, CON, PAT, etc. Add it to the ignore-words-list, matching the
pattern every other technical-token exemption in .codespellrc uses.
---
 .codespellrc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.codespellrc b/.codespellrc
index c554845f3..7f9b6d589 100644
--- a/.codespellrc
+++ b/.codespellrc
@@ -56,7 +56,9 @@
 
 # ans - bash and powershell variable short for answer
 
-ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes,nin,FO,CAF,Parth,ans
+# GUD - "Guideline" identifier prefix in the create-implementation-plan skill spec (alongside REQ, SEC, CON, PAT, etc.)
+
+ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes,nin,FO,CAF,Parth,ans,gud
 
 # Skip certain files and directories
 

From 24171ab9ee59d3aae3b9e2fde6ffe3b39fe22df3 Mon Sep 17 00:00:00 2001
From: Komal Vardhan Lolugu <67476199+KomalSrinivasan@users.noreply.github.com>
Date: Mon, 29 Jun 2026 09:20:24 +0530
Subject: [PATCH 3/3] create-implementation-plan: clarify declaration vs
 reference (#1989 review)

basilevs flagged that calling out DEP-* specifically was misleading,
because any identifier can appear as a reference. A TASK body can
cite a REQ, one TASK can cite another, and so on. The original
phrasing made it sound like DEP-* was the only prefix allowed to
recur.

Rewrite the rule to lead with "uniquely declared":
- Define declaration as the leading bullet/cell ID (e.g., the table
  row in Implementation Phase N, or '- **REQ-001**:').
- Say explicitly that references elsewhere in the plan are expected
  and not collisions, with concrete examples (TASK citing REQ,
  TASK citing TASK, Dependencies pointing at a DEP declared upstream).
- Tighten the check intro to call (1) and (2) declaration-targeted
  gates and (3) a broad informational scan that will see references.

Bash checks unchanged; they already encode the declaration-vs-reference
distinction via the table-cell and bullet-prefix anchors.
---
 skills/create-implementation-plan/SKILL.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/skills/create-implementation-plan/SKILL.md b/skills/create-implementation-plan/SKILL.md
index bb64d622b..4540a479c 100644
--- a/skills/create-implementation-plan/SKILL.md
+++ b/skills/create-implementation-plan/SKILL.md
@@ -60,11 +60,11 @@ All implementation plans must strictly adhere to the following template. Each se
 - All identifier prefixes must follow the specified format
 - Tables must include all required columns
 - No placeholder text may remain in the final output
-- **Identifiers must be unique.** Every declaration of `REQ-NNN`, `SEC-NNN`, `CON-NNN`, `GUD-NNN`, `PAT-NNN`, `GOAL-NNN`, `TASK-NNN`, `ALT-NNN`, `DEP-NNN`, `FILE-NNN`, `TEST-NNN`, `RISK-NNN`, and `ASSUMPTION-NNN` must appear exactly once across the plan. `DEP-*` may appear in multiple sections (for example, Requirements and Dependencies) as a reference; that is not a declaration collision.
+- **Identifiers must be uniquely declared.** Every identifier (`REQ-NNN`, `SEC-NNN`, `CON-NNN`, `GUD-NNN`, `PAT-NNN`, `GOAL-NNN`, `TASK-NNN`, `ALT-NNN`, `DEP-NNN`, `FILE-NNN`, `TEST-NNN`, `RISK-NNN`, `ASSUMPTION-NNN`) must be **declared exactly once**. A declaration is where the identifier introduces a row: the leading cell in a TASK/GOAL table row, or the bolded prefix in a bullet line like `- **REQ-001**: ...`. The same identifier may then appear any number of times as a **reference** elsewhere in the plan (a `TASK` body citing a `REQ`, one `TASK` citing another `TASK`, the Dependencies section pointing at a `DEP` already declared upstream, etc.). References are expected and not collisions.
 
 ## Identifier Uniqueness Check
 
-Run these checks before finalizing the plan. The first two must return zero rows. The third is informational.
+Run these checks before finalizing the plan. Checks (1) and (2) target declarations and must return zero rows. Check (3) is a broad informational scan: it will surface valid references too, so use it for awareness rather than as a gate.
 
 ```bash
 # Set PLAN_FILE to the plan being validated.