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
This commit is contained in:
Lex Christopherson
2026-01-15 17:04:47 -06:00
parent faaeae25b1
commit ccac62d8ae

View File

@@ -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> <research_pitfalls>
<purpose> <purpose>
@@ -14,18 +32,18 @@ This document catalogs research mistakes discovered in production use, providing
```xml ```xml
<verification_checklist> <verification_checklist>
**CRITICAL**: Verify ALL configuration scopes: **CRITICAL**: Verify ALL configuration scopes:
□ User/global scope - System-wide configuration - User/global scope - System-wide configuration
□ Project scope - Project-level configuration files - Project scope - Project-level configuration files
□ Local scope - Project-specific user overrides - Local scope - Project-specific user overrides
□ Workspace scope - IDE/tool workspace settings - Workspace scope - IDE/tool workspace settings
□ Environment scope - Environment variables - Environment scope - Environment variables
</verification_checklist> </verification_checklist>
``` ```
</pitfall_config_scope> </pitfall_config_scope>
<pitfall_search_vagueness> <pitfall_search_vagueness>
**What**: Asking researchers to "search for documentation" without specifying where **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 **Why it happens**: Vague research instructions don't specify exact sources
**Prevention**: **Prevention**:
```xml ```xml
@@ -48,25 +66,25 @@ Search queries (use WebSearch):
**Prevention**: **Prevention**:
```xml ```xml
<verification_checklist> <verification_checklist>
□ Check current official documentation - Check current official documentation
□ Review changelog/release notes for recent updates - Review changelog/release notes for recent updates
□ Verify version numbers and publication dates - Verify version numbers and publication dates
□ Cross-reference multiple authoritative sources - Cross-reference multiple authoritative sources
</verification_checklist> </verification_checklist>
``` ```
</pitfall_deprecated_features> </pitfall_deprecated_features>
<pitfall_tool_variations> <pitfall_tool_variations>
**What**: Conflating capabilities across different tools/environments **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 **Why it happens**: Not explicitly checking each environment separately
**Prevention**: **Prevention**:
```xml ```xml
<verification_checklist> <verification_checklist>
□ Claude Desktop capabilities - Claude Desktop capabilities
□ Claude Code capabilities - Claude Code capabilities
□ VS Code extension capabilities - VS Code extension capabilities
□ API/SDK capabilities - API/SDK capabilities
Document which environment supports which features Document which environment supports which features
</verification_checklist> </verification_checklist>
``` ```
@@ -96,10 +114,10 @@ For any "X is not possible" or "Y is the only way" statement:
```xml ```xml
<verification_checklist> <verification_checklist>
Enumerate ALL known options FIRST: Enumerate ALL known options FIRST:
□ Option 1: [specific item] - Option 1: [specific item]
□ Option 2: [specific item] - Option 2: [specific item]
□ Option 3: [specific item] - Option 3: [specific item]
□ Check for additional unlisted options - Check for additional unlisted options
For each option above, document: For each option above, document:
- Existence (confirmed/not found/unclear) - Existence (confirmed/not found/unclear)