From f430e2ffa876d9c351d13f650936a392083e4708 Mon Sep 17 00:00:00 2001
From: GitHub Copilot <copilot@github.com>
Date: Sat, 27 Dec 2025 21:47:27 +0000
Subject: [PATCH] docs: Add critical warning about reusable workflow references

When copying agents-63-issue-intake.yml from Workflows to consumer repos,
it contains a LOCAL reference to reusable-agents-issue-bridge.yml that
doesn't exist in consumer repos and will cause issue intake to fail.

Added:
1. Critical warning in section 4.1b with:
   - Explanation of the problem
   - Before/after code showing what to change
   - Alternative: copy from Template instead (already correct)

2. New item #5 in Common Mistakes section

This was discovered when Manager-Database issue #49 and trip-planner
issue intake failed after copying agents-63-issue-intake.yml directly
from Workflows without fixing the local reference.
---
 docs/templates/SETUP_CHECKLIST.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/templates/SETUP_CHECKLIST.md b/docs/templates/SETUP_CHECKLIST.md
index 02eb18d83..87347f850 100644
--- a/docs/templates/SETUP_CHECKLIST.md
+++ b/docs/templates/SETUP_CHECKLIST.md
@@ -278,6 +278,27 @@ curl -o .github/workflows/maint-sync-workflows.yml \
   https://raw.githubusercontent.com/stranske/Travel-Plan-Permission/main/.github/workflows/maint-sync-workflows.yml
 ```
 
+> **⚠️ CRITICAL: Fix reusable workflow references after copying!**
+> 
+> The `agents-63-issue-intake.yml` file in the Workflows repo contains a LOCAL 
+> reference to `reusable-agents-issue-bridge.yml`. This works in Workflows but
+> **will break in consumer repos** because the file doesn't exist locally.
+> 
+> After copying, you MUST change line ~1171 from:
+> ```yaml
+> uses: ./.github/workflows/reusable-agents-issue-bridge.yml
+> ```
+> To the remote reference:
+> ```yaml
+> uses: stranske/Workflows/.github/workflows/reusable-agents-issue-bridge.yml@main
+> ```
+> 
+> **Alternative**: Copy from Template repo instead (already has correct reference):
+> ```bash
+> curl -o .github/workflows/agents-63-issue-intake.yml \
+>   https://raw.githubusercontent.com/stranske/Template/main/.github/workflows/agents-63-issue-intake.yml
+> ```
+
 ### 4.2 Autofix Versions Configuration
 
 > **Important**: Each repository maintains its own `autofix-versions.env` file
@@ -800,6 +821,7 @@ inputs:
 2. **Missing commit status** — Keepalive checks for `Gate / gate` status to know when CI passes
 3. **Wrong workflow name in trigger** — The `workflows:` array must match the exact workflow `name:` field
 4. **Missing scripts** — Scripts are NOT automatically synced; they must exist in consumer repo
+5. **Local reusable workflow references** — When copying `agents-63-issue-intake.yml` from Workflows, it has a LOCAL reference to `reusable-agents-issue-bridge.yml` that doesn't exist in consumer repos. Must change to remote reference: `stranske/Workflows/.github/workflows/reusable-agents-issue-bridge.yml@main`
 
 ---