diegosouzapw API Documentation Discovery
Overview
When your training data conflicts with current API versions, STOP guessing and START discovering. This skill guides you to find current, accurate documentation using language-specific tools.
Core principle: Training data ages. Installed versions are truth. Use discovery tools to find what's actually there.
When to Use
Reactive Triggers (MUST use after these):
- ✅ 2+ failed attempts with same library/API
- ✅ Error patterns: "method not found", "wrong number of arguments", "unknown flag", "undefined method"
- ✅ Version mismatch symptoms in stack traces
Proactive Red Flags (STOP and check docs when you notice):
- ⚠️ You're confident about API usage but haven't verified current version
- ⚠️ User is confident but their syntax keeps failing
- ⚠️ You're making "one more tweak" to syntax
- ⚠️ You're using phrases like "should work", "likely correct", "probably just"
- ⚠️ You're pattern-matching from training data without verification
- ⚠️ You're about to claim something is "documented" without checking
When NOT to use:
- First attempt with clear error message pointing to fix
- Errors unrelated to API usage (logic bugs, type errors in your code)
The Discovery Workflow
Step 1: STOP Guessing
Recognize the trigger. Don't make another attempt based on patterns or user confidence.
Step 2: Identify Context
- What library/framework is failing? (check imports, stack traces, go.mod/Gemfile)
- What version is installed? (language tools show this)
- What operation are you trying? (the actual goal, not the syntax attempt)
Step 3: Use Language Discovery Tools
Check language-specific reference for HOW to discover documentation:
references/go.md- Go module explorationreferences/ruby.md- Ruby gem exploration
Follow progressive discovery: docs → examples → source
Step 4: Load Framework Reference (if available)
If framework-specific reference exists, load it for curated patterns:
references/go/cobra.md- Cobra CLI patternsreferences/ruby/rails.md- Rails patternsreferences/ruby/karafka.md- Karafka patterns
Step 5: Verify Before Using
- Found API signature? Verify it matches your use case
- Found example? Adapt it, don't just copy pattern from memory
- Found docs? Read them, don't skim for confirmation
Common Anti-Patterns
| Rationalization | Reality |
|---|---|
| "User is confident, syntax is probably right" | User confidence ≠ current API. Verify. |
| "Training data shows this pattern" | Training data ages. Check installed version. |
| "Let me try one more variation" | Guessing wastes time. Check docs now. |
| "This is documented somewhere" | Then go READ it before claiming confidence. |
| "Should be simple, just tweak syntax" | Simplicity bias. Use discovery tools. |
| "We've spent enough time on this" | Sunk cost fallacy. 2 min checking docs beats 20 min guessing. |
Navigation: Language References
Available language discovery guides:
references/go.md- Go:go doc,go list, example/test scanningreferences/ruby.md- Ruby:bundle info,ri, gem exploration
Path issues: Some languages need tool managers (mise, asdf). If go or bundle not found, try mise exec -- <command>.
Extending this skill: To add a new language reference, see references/WRITING.md for principles and template.
Navigation: Framework References
Available framework cheat sheets:
references/go/cobra.md- Cobra CLI library patternsreferences/ruby/rails.md- Rails framework patterns (coming)references/ruby/karafka.md- Karafka framework patterns (coming)
Red Flags - When You're About to Fail
STOP immediately if you catch yourself:
- Making confident API claims without checking current docs
- Accepting user's confident syntax without verification
- Trying "one more variation" based on pattern-matching
- Using phrases: "should work", "likely", "probably", "common pattern"
- Creating narrative about what "likely happened" without evidence
- Claiming something is "documented" without reading it
All of these mean: Use discovery tools NOW.
After Finding Documentation
- Verify: API signature matches your use case
- Adapt: Use the pattern for your specific need
- Test: Try the verified approach
- Update understanding: Note what changed from your training data
Real-World Impact
Without this skill:
- 15+ minutes guessing at syntax variations
- Confident claims based on outdated training data
- User frustration from repeated failures
With this skill:
- 2 minutes checking current docs
- Accurate API usage from installed version
- Fast resolution based on truth, not patterns