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:
@@ -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)
|
||||||
|
|||||||
Reference in New Issue
Block a user