From ccac62d8ae5b971c5202e04a34e474ebdf70492d Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Thu, 15 Jan 2026 17:04:47 -0600
Subject: [PATCH] docs(14-03): deprecate research-pitfalls.md reference

- Content consolidated into gsd-researcher agent
- Points to verification_protocol section in agent
- Preserved content below notice for reference
---
 get-shit-done/references/research-pitfalls.md | 56 ++++++++++++-------
 1 file changed, 37 insertions(+), 19 deletions(-)

diff --git a/get-shit-done/references/research-pitfalls.md b/get-shit-done/references/research-pitfalls.md
index 5b5fe099e..1575919f7 100644
--- a/get-shit-done/references/research-pitfalls.md
+++ b/get-shit-done/references/research-pitfalls.md
@@ -1,3 +1,21 @@
+# Research Pitfalls Reference
+
+## DEPRECATED
+
+**This reference has been consolidated into the gsd-researcher agent.**
+
+The verification protocols and pitfall patterns now live in:
+- `agents/gsd-researcher.md` (section: `<verification_protocol>`)
+
+The content below is preserved for reference but is no longer the primary source.
+
+---
+
+*Deprecated: 2026-01-15*
+*Replaced by: agents/gsd-researcher.md*
+
+---
+
 <research_pitfalls>
 
 <purpose>
@@ -14,18 +32,18 @@ This document catalogs research mistakes discovered in production use, providing
 ```xml
 <verification_checklist>
 **CRITICAL**: Verify ALL configuration scopes:
-□ User/global scope - System-wide configuration
-□ Project scope - Project-level configuration files
-□ Local scope - Project-specific user overrides
-□ Workspace scope - IDE/tool workspace settings
-□ Environment scope - Environment variables
+- User/global scope - System-wide configuration
+- Project scope - Project-level configuration files
+- Local scope - Project-specific user overrides
+- Workspace scope - IDE/tool workspace settings
+- Environment scope - Environment variables
 </verification_checklist>
 ```
 </pitfall_config_scope>
 
 <pitfall_search_vagueness>
 **What**: Asking researchers to "search for documentation" without specifying where
-**Example**: "Research MCP documentation" → finds outdated community blog instead of official docs
+**Example**: "Research MCP documentation" -> finds outdated community blog instead of official docs
 **Why it happens**: Vague research instructions don't specify exact sources
 **Prevention**:
 ```xml
@@ -48,25 +66,25 @@ Search queries (use WebSearch):
 **Prevention**:
 ```xml
 <verification_checklist>
-□ Check current official documentation
-□ Review changelog/release notes for recent updates
-□ Verify version numbers and publication dates
-□ Cross-reference multiple authoritative sources
+- Check current official documentation
+- Review changelog/release notes for recent updates
+- Verify version numbers and publication dates
+- Cross-reference multiple authoritative sources
 </verification_checklist>
 ```
 </pitfall_deprecated_features>
 
 <pitfall_tool_variations>
 **What**: Conflating capabilities across different tools/environments
-**Example**: "Claude Desktop supports X" ≠ "Claude Code supports X"
+**Example**: "Claude Desktop supports X" does not mean "Claude Code supports X"
 **Why it happens**: Not explicitly checking each environment separately
 **Prevention**:
 ```xml
 <verification_checklist>
-□ Claude Desktop capabilities
-□ Claude Code capabilities
-□ VS Code extension capabilities
-□ API/SDK capabilities
+- Claude Desktop capabilities
+- Claude Code capabilities
+- VS Code extension capabilities
+- API/SDK capabilities
 Document which environment supports which features
 </verification_checklist>
 ```
@@ -96,10 +114,10 @@ For any "X is not possible" or "Y is the only way" statement:
 ```xml
 <verification_checklist>
 Enumerate ALL known options FIRST:
-□ Option 1: [specific item]
-□ Option 2: [specific item]
-□ Option 3: [specific item]
-□ Check for additional unlisted options
+- Option 1: [specific item]
+- Option 2: [specific item]
+- Option 3: [specific item]
+- Check for additional unlisted options
 
 For each option above, document:
 - Existence (confirmed/not found/unclear)