Problem
Workflow commands that depend on external APIs (Jira, Confluence, Linear, etc.) frequently fail due to:
- Query syntax errors (162 'wrong approach' events in usage data)
- API rate limits or timeouts
- Authentication issues
- Network failures
Currently, Claude retries with different approaches through trial-and-error, wasting time and often ending sessions incomplete.
Proposal
Create a fallback strategies reference that documents explicit recovery patterns for external integrations:
Example Structure
## Ticketing System Fallbacks
### When API query fails (after 2 attempts):
1. Check if data is cached locally in `.claude/cache/`
2. Try alternative query syntax (document known-working patterns)
3. Use web API directly via curl if SDK fails
4. Ask user to provide the data manually
### When authentication fails:
1. Check credential freshness
2. Prompt user to re-authenticate
3. Continue with cached/partial data if non-blocking
Benefits
Relates To
Problem
Workflow commands that depend on external APIs (Jira, Confluence, Linear, etc.) frequently fail due to:
Currently, Claude retries with different approaches through trial-and-error, wasting time and often ending sessions incomplete.
Proposal
Create a fallback strategies reference that documents explicit recovery patterns for external integrations:
Example Structure
Benefits
Relates To