Add fallback strategies reference for external integrations

Author: JeffallanCreated Feb 5, 2026Updated Feb 5, 2026
Labelsdocumentationenhancement

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

markdown
## 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

  • Reduces time spent on failed approaches
  • Provides consistent error recovery across workflows
  • Complements #52 (Error Recovery) with integration-specific guidance

Relates To

  • #52 Error Recovery: Resume/rollback/retry mechanisms
  • #62 Generalize workflow commands for multiple systems