Skill: Offline Fallback

Purpose

Detect when Jira/Confluence is unavailable and store operations locally for later sync. This ensures work can continue even when Atlassian services are temporarily down.

When to Use

• MCP tool call fails with service unavailability error
• MCP tool call fails with authentication error
• MCP server is not running or connection fails

MCP Tools Used

None - this skill handles local file operations only.

Configuration

Pending items are stored in the active workflow directory:

workflow/active/{workflow-name}/pending/

---

Unavailability Detection

Errors That Trigger Local Storage

Error Type	Detection Patterns
Service Unavailable	HTTP 503, "service unavailable", "service temporarily unavailable"
Gateway Timeout	HTTP 504, "gateway timeout"
Authentication Failure	HTTP 401, "unauthorized", "token expired", "authentication failed"
Connection Failure	ECONNREFUSED, ETIMEDOUT, "connection refused", "connection timeout"
MCP Server Failure	"MCP server not running", "MCP connection failed", "server not available"

Errors That Should NOT Trigger Local Storage

Error Type	Reason
400 Bad Request	Invalid data - fix the request payload
403 Forbidden	Permission issue - fix permissions
404 Not Found	Target doesn't exist - handle differently

---

Procedure: Detect Unavailability

Check if an error indicates service/auth unavailability:

function isUnavailabilityError(error) {
  const errorString = String(error).toLowerCase();
  const unavailabilityPatterns = [
    // HTTP status codes
    '503', 'service unavailable',
    '504', 'gateway timeout',
    '401', 'unauthorized', 'token expired', 'authentication failed',
    // Connection errors
    'econnrefused', 'etimedout', 'connection refused', 'connection timeout',
    // MCP errors
    'mcp server', 'server not available', 'mcp connection'
  ];

  return unavailabilityPatterns.some(pattern => errorString.includes(pattern));
}

---

Procedure: Store Fallback Operation

When unavailability is detected, store the operation locally:

Step 1: Create Pending Directory

mkdir -p workflow/active/{workflow-name}/pending/

Step 2: Generate Operation ID

Use sequential numbering with timestamp: 001-jira-comment.json, 002-confluence-page.json

Step 3: Write Pending File

File Format:

{
  "id": "001",
  "created_at": "2025-01-17T10:30:00Z",
  "service": "jira",
  "operation": "add_comment",
  "original_error": "503 Service Unavailable",
  "target": {
    "issue_key": "PROJECT-45"
  },
  "payload": {
    "cloudId": "abc123",
    "issueIdOrKey": "PROJECT-45",
    "commentBody": "..."
  },
  "context": {
    "agent": "Senior Developer",
    "step": "Code Review",
    "workflow": "development-PROJECT-45"
  }
}

Supported Operations

Service	Operation	Target Fields
jira	create_issue	project_key, issue_type
jira	edit_issue	issue_key
jira	add_comment	issue_key
jira	transition_issue	issue_key, transition_name
confluence	create_page	space_key, parent_page
confluence	update_page	page_id or page_title

---

Procedure: Notify User

After storing locally, inform the user:

⚠️ **Jira/Confluence Unavailable**

The operation has been stored locally for later sync:
- Operation: Add comment to PROJECT-45
- Stored: workflow/active/development-PROJECT-45/pending/001-jira-comment.json

Run `/sync` when services are available to push pending changes.
Workflow will continue without blocking.

---

Procedure: Check Pending Count

List pending items in a workflow:

ls workflow/active/{workflow-name}/pending/*.json 2>/dev/null | wc -l

Or read all pending files to get details:

for f in workflow/active/{workflow-name}/pending/*.json; do
  cat "$f" | jq '{id, service, operation, target, created_at}'
done

---

Integration with Existing Skills

When any Jira/Confluence skill encounters an unavailability error:

1. Catch the error from MCP tool call
2. Check error type using isUnavailabilityError()
3. If unavailable:
   • Call this skill to store operation locally
   • Notify user
   • Return success (operation is queued)
   • Continue workflow
4. If other error:
   • Handle normally (don't store locally)
   • May block workflow depending on error type

---

Example: Wrapping a Jira Comment

try {
  // Attempt normal MCP call
  await Atlassian:addCommentToJiraIssue({
    cloudId: config.jira.cloudId,
    issueIdOrKey: "PROJECT-45",
    commentBody: commentText
  });
} catch (error) {
  if (isUnavailabilityError(error)) {
    // Store locally for later sync
    await storeOfflineFallback({
      service: "jira",
      operation: "add_comment",
      original_error: error.message,
      target: { issue_key: "PROJECT-45" },
      payload: {
        cloudId: config.jira.cloudId,
        issueIdOrKey: "PROJECT-45",
        commentBody: commentText
      },
      context: {
        agent: currentAgent,
        step: currentStep,
        workflow: workflowId
      }
    });
    // Notify user and continue
    console.log("⚠️ Jira unavailable - comment stored locally");
  } else {
    // Re-throw other errors
    throw error;
  }
}

---

Integration with Atlassian Cache

This skill works in conjunction with skills/resilience/atlassian-cache/ for complete offline support:

Operation	Offline Behavior
Read (fetch ticket/page)	Read from atlassian-cache/
Write (comment, transition, update)	Store in pending/ queue

Read from Cache When Unavailable

async function getTicketWithFallback(ticketKey) {
  try {
    // Try live fetch
    const ticket = await Atlassian:getJiraIssue({
      cloudId: config.jira.cloudId,
      issueIdOrKey: ticketKey
    });
    // Update cache opportunistically
    await cacheTicket(ticket);
    return { data: ticket, source: "live" };
  } catch (error) {
    if (isUnavailabilityError(error)) {
      // Try cache
      const cached = await readFromCache(ticketKey);
      if (cached) {
        return {
          data: cached,
          source: "cache",
          cached_at: cached.cached_at,
          warning: `Using cached data from ${cached.cached_at}`
        };
      }
      // Not in cache
      throw new Error(
        `Jira unavailable and ${ticketKey} not in cache. ` +
        `Run /offline-prepare ${ticketKey} when online.`
      );
    }
    throw error;
  }
}

Complete Offline Flow

┌─────────────────────────────────────────────────────────────────┐
│                    OFFLINE MODE FLOW                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   BEFORE GOING OFFLINE                                           │
│   ────────────────────                                           │
│   User runs: /offline-prepare EPIC-100                           │
│   → Fetches tickets → Stores in atlassian-cache/                 │
│                                                                  │
│   WHILE OFFLINE                                                  │
│   ─────────────                                                  │
│   Read ticket:  atlassian-cache/jira/PROJECT-123.json            │
│   Write comment: → pending/001-jira-comment.json                 │
│   Transition:    → pending/002-jira-transition.json              │
│                                                                  │
│   BACK ONLINE                                                    │
│   ───────────                                                    │
│   User runs: /sync                                               │
│   → Pushes pending/ to Jira → Deletes synced files               │
│   → Optionally refresh cache with /offline-prepare               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Notify User of Cache Usage

When serving cached data:

⚠️ **Using Cached Data**

Jira is currently unavailable. Showing cached data:

  Ticket: PROJECT-123
  Cached: 2 hours ago (2026-01-17 10:00)

Note: This data may be outdated. Changes you make will be
queued locally and synced when Jira is available again.

---

Error Handling

Scenario	Action
Cannot create pending directory	Log error, notify user, may need to block
Cannot write pending file	Log error, notify user, may need to block
Disk full	Notify user, cannot store locally
Ticket not in cache	Suggest running /offline-prepare
Cache corrupted	Delete corrupted file, re-fetch when online