From d7a419c92fed950254c7825fd8717e1b948d8268 Mon Sep 17 00:00:00 2001
From: Pedro Rodrigues <pedro.rodrigues@supabase.io>
Date: Wed, 28 Jan 2026 12:23:05 +0000
Subject: [PATCH] research agent keeps track of the source URLs

---
 .claude/agents/docs-researcher.md | 32 +++++++++++++++++++++++++++++--
 .claude/agents/pr-writer.md       | 22 ++++++++++++++++++---
 2 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/.claude/agents/docs-researcher.md b/.claude/agents/docs-researcher.md
index 9103447..3eb3630 100644
--- a/.claude/agents/docs-researcher.md
+++ b/.claude/agents/docs-researcher.md
@@ -22,7 +22,25 @@ Use `mcp__claude_ai_Supabase__search_docs` to find official Supabase documentati
 - Common use cases and examples
 - Known limitations or caveats
 
-**2. Kiro Powers Workflows**
+**2. Troubleshooting Guides**
+Fetch product-specific troubleshooting guides from Supabase docs:
+
+URL pattern: `https://supabase.com/docs/guides/troubleshooting?products={product}`
+
+Available products:
+- `realtime` - Realtime subscriptions and channels
+- `database` - Database operations and Postgres
+- `auth` - Authentication and user management
+- `storage` - File storage and buckets
+- `edge-functions` - Edge Functions
+- `ai` - AI and vector operations
+- `cli` - Supabase CLI
+- `platform` - Platform and project management
+- `self-hosting` - Self-hosting Supabase
+
+Example: `https://supabase.com/docs/guides/troubleshooting?products=realtime`
+
+**3. Kiro Powers Workflows**
 Fetch workflows from https://github.com/supabase-community/kiro-powers/tree/main/powers:
 - Find the relevant power for the Supabase product
 - Extract workflow steps and logic
@@ -30,13 +48,23 @@ Fetch workflows from https://github.com/supabase-community/kiro-powers/tree/main
 - **Ignore Kiro-specific parameters** (IDE integrations, UI elements)
 - Focus on the actual Supabase operations and sequences
 
-**3. Gap Analysis**
+**4. Gap Analysis**
 Identify what's unique to Supabase vs vanilla alternatives:
 - Extensions or features not available
 - Different configurations or defaults
 - Required workarounds
 - Supabase-specific patterns
 
+## IMPORTANT: Track Source URLs
+
+**Always record the exact URLs where research information was found.** This enables:
+- Manual verification of information accuracy
+- Easy updates when documentation changes
+- Proper attribution of sources
+- Quick navigation to original context
+
+Include full URLs (not just page titles) in your research output.
+
 ## Output Guidance
 
 Provide a comprehensive research summary that includes:
diff --git a/.claude/agents/pr-writer.md b/.claude/agents/pr-writer.md
index 9a7cd5a..4fecea4 100644
--- a/.claude/agents/pr-writer.md
+++ b/.claude/agents/pr-writer.md
@@ -33,11 +33,18 @@ Read any SKILL.md files to see what was added or changed.
 
 **4. Review Conversation Context**
 From the conversation history, identify:
-- Sources consulted (Supabase docs, kiro-powers, etc.)
+- **Source URLs consulted** (Supabase docs, kiro-powers, troubleshooting guides, etc.)
 - Architectural decisions made and their rationale
 - User preferences or requirements that shaped the design
 - Any trade-offs or alternatives considered
 
+**5. Collect Source URLs**
+Look for any URLs that were used during research:
+- Documentation pages
+- Troubleshooting guides
+- GitHub repositories (kiro-powers, etc.)
+- API references
+
 ## PR Description Format
 
 Use this exact structure:
@@ -63,9 +70,18 @@ Key architectural and content decisions made during development:
 2. **[Decision 2]**: [What was decided and why]
 3. **[Decision 3]**: [What was decided and why]
 
+## Sources
+
+[If source URLs were provided during research, list them here. This enables manual verification of information accuracy.]
+
+- [Page Title](https://full-url-here)
+- [Another Page](https://another-url-here)
+
+_If no source URLs were tracked, omit this section._
+
 ## Additional context
 
-[Any other relevant information: sources consulted, limitations, future improvements, trade-offs considered, related issues, etc.]
+[Any other relevant information: limitations, future improvements, trade-offs considered, related issues, etc.]
 ```
 
 ## Writing Guidelines
@@ -73,7 +89,7 @@ Key architectural and content decisions made during development:
 **DO:**
 - Describe changes at the conceptual level
 - Explain the "why" behind organizational choices
-- Credit specific documentation sources in Additional context
+- **Include source URLs in the Sources section when provided**
 - Mention trade-offs or alternatives considered
 - Use concrete examples of what the changes enable
 - Include decisions that shaped the implementation