bug-resume

Skill: bug-resume (V3 - NEW)

Configuration Required: This skill requires project configuration. If .claude/bugflow/config/environment.json does not exist, prompt the user to run /bugflow:bug-setup first.

Table of Contents

• Metadata
• Description
• Execution Flow
  • Step 1: Check for Bug ID Argument
  • Step 2: Scan for Incomplete Workflows
  • Step 3: Resume Specific Workflow
  • Step 4: Determine Recovery Action
  • Step 5: Offer Resume Options
  • Step 6: Execute Resume
  • Step 7: Report Resume Status
• Error Handling
• State Helpers
• Usage Examples
• Integration with Lock System
• Notes

Metadata

• Command: /bug-resume [bug_id]
• Aliases: bug resume, bugresume
• Args: bug_id (optional) - Bugzilla bug ID

Description

Resume an interrupted bug workflow from its last checkpoint. If a Claude Code session ends mid-workflow (crash, timeout, user quit), this command allows recovering and continuing.

Two modes:

1. With bug_id: Resume specific workflow
2. Without bug_id: Scan for all incomplete workflows and let user choose

---

Execution Flow

Step 1: Check for Bug ID Argument

If bug_id provided: Go to Step 3 (Resume Specific Workflow)

If no bug_id: Go to Step 2 (Scan for Incomplete Workflows)

---

Step 2: Scan for Incomplete Workflows

Scan <paths.stateDir> from project config (default: .bugflow) for incomplete workflows.

// Find all state files
const stateDir = getProjectConfig('paths.stateDir') || '.bugflow';
const stateFiles = await glob(`${stateDir}/*.json`);

// Exclude lock files, logs, and closed workflows
const incompleteWorkflows = [];

for (const file of stateFiles) {
  if (file.endsWith('.lock') || file.includes('_logs')) continue;

  const state = await readJSON(file);
  if (state.state !== 'CLOSED' && state.state !== 'DONE_BE') {
    incompleteWorkflows.push({
      bugId: state.bugId,
      title: state.bugzillaData?.title || 'Unknown',
      state: state.state,
      branch: state.branch,
      updatedAt: state.updatedAt || state.createdAt,
      age: calculateAge(state.updatedAt || state.createdAt)
    });
  }
}

If no incomplete workflows found:

No incomplete workflows found.

All workflows in <paths.stateDir> are either:
- Completed (CLOSED state)
- Backend handoff (DONE_BE state)

To start a new workflow: /bug-start <bug_id>

If incomplete workflows found:

Found <N> incomplete workflow(s):

┌─────────────────────────────────────────────────────────────────┐
│ #  │ Bug ID │ Title                    │ State     │ Age       │
├─────────────────────────────────────────────────────────────────┤
│ 1  │ 6312   │ Delete favorites folder  │ PLAN_FE   │ 2 hours   │
│ 2  │ 6307   │ FROM lists departments   │ EXECUTE   │ 1 day     │
│ 3  │ 6231   │ Search address code      │ VERIFY    │ 3 days    │
└─────────────────────────────────────────────────────────────────┘

Enter bug ID to resume (or 'q' to quit):

Wait for user input using AskUserQuestion tool.

---

Step 3: Resume Specific Workflow

Load state file:

Read({ file_path: "<paths.stateDir>/<bugId>.json" })

If not found:

No workflow found for bug <bugId>.

Possible causes:
1. Workflow was never started
2. Workflow was reset with --hard
3. State file was deleted

To start a new workflow: /bug-start <bugId>

If found, show current state:

Bug <bugId>: <title>

Current State: <state>
Branch: <branch>
Last Updated: <timestamp> (<age> ago)
Verdict: <verdict>

Progress:
[x] Scout complete
[x] Dossier created
[x] Analysis complete
[ ] Plan generated
[ ] Changes applied
[ ] Verification complete

---

Step 4: Determine Recovery Action

Based on current state, offer appropriate recovery options.

Phase Recovery Logic

Current State	Recovery Action	Command to Run
INIT, SCOUT	Restart from beginning	/bug-start <bugId>
DOSSIER	Re-run analysis	Continue from Step 5 (Analysis)
ANALYZE	Re-run analysis	Continue from Step 5 (Analysis)
VERDICT	Generate plan	/bug-plan <bugId>
PLAN_FE	Validate plan	Continue from validation
TEST_SPEC	Validate plan	Continue from validation
VALIDATE	Show plan, await approval	Show plan + /bug-accept <bugId>
FEATURE_DESIGN	Show design, await approval	Show design + /bug-accept <bugId>
EXECUTE	Restart execution	/bug-accept <bugId> (idempotent)
VERIFY	Re-run verification	/bug-verify <bugId>
VERIFY_FAIL	Show failure, offer re-plan	Show failure + options
STALLED	Show error, offer reset	Show error + /bug-reset <bugId>
BLOCKED	Show blocker, offer reset	Show blocker + options

---

Step 5: Offer Resume Options

Present options to user:

Bug <bugId> can be resumed from <state>.

Options:
1. Resume from current checkpoint (recommended)
2. Reset to previous phase
3. Reset entirely and start fresh
4. Cancel

What would you like to do?

Use AskUserQuestion tool with options:

{
  "questions": [{
    "question": "How would you like to resume bug <bugId>?",
    "header": "Resume",
    "options": [
      {
        "label": "Resume from checkpoint (Recommended)",
        "description": "Continue from <state> where the workflow stopped"
      },
      {
        "label": "Reset to <previous_phase>",
        "description": "Go back one step and retry from there"
      },
      {
        "label": "Start fresh",
        "description": "Reset everything and restart the workflow"
      },
      {
        "label": "Cancel",
        "description": "Do nothing, keep workflow as-is"
      }
    ],
    "multiSelect": false
  }]
}

---

Step 6: Execute Resume

Based on user choice:

Option 1: Resume from Checkpoint

Acquire/verify lock (see ${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/workflow-lock.md):

// Check if lock exists
const stateDir = getProjectConfig('paths.stateDir') || '.bugflow';
const lockPath = `${stateDir}/${bugId}.lock`;
if (await fileExists(lockPath)) {
  const lock = await readJSON(lockPath);
  const expired = new Date() > new Date(lock.expiresAt);

  if (!expired) {
    // Lock still active - may be another session
    console.warn(`Warning: Lock exists from previous session (${lock.sessionId})`);
    // Continue anyway - user explicitly chose to resume
  }
}

// Create new lock for this session
const newLock = {
  bugId,
  acquiredAt: new Date().toISOString(),
  sessionId: `wf-${bugId}-${generateRandomId(8)}`,
  phase: currentState.state,
  expiresAt: new Date(Date.now() + 4 * 60 * 60 * 1000).toISOString()
};
await writeJSON(lockPath, newLock);

Log resume event:

{
  "event": "WORKFLOW_RESUME",
  "details": {
    "from_phase": "<current_state>",
    "previous_session": "<old_session_id>",
    "new_session": "<new_session_id>"
  }
}

Recover Working Memory (V3):

Working memory contains important runtime state that should persist across resume:

• metrics: Agent durations, retry counts, performance data
• errorLog: Previous errors for debugging
• antiPatterns: Patterns to avoid from failed revisions
• sharedContext: Verdict, risk level, plan version

// Attempt to load existing working memory
const stateDir = getProjectConfig('paths.stateDir') || '.bugflow';
const workingMemoryPath = `${stateDir}/${bugId}/working-memory.json`;
let workingMemory = null;

if (await fileExists(workingMemoryPath)) {
  try {
    workingMemory = await readJSON(workingMemoryPath);
    console.log(`Recovered working memory for bug ${bugId}`);

    // Update for new session
    workingMemory.workflowId = newLock.sessionId;
    workingMemory.updatedAt = new Date().toISOString();

    // Preserve but don't clear important fields
    // - metrics: Keep for full workflow performance tracking
    // - errorLog: Keep for debugging history
    // - antiPatterns: Keep to avoid repeating mistakes

    await writeJSON(workingMemoryPath, workingMemory);

  } catch (readError) {
    console.warn(`Could not read working memory: ${readError.message}`);
    // Continue without working memory - will be recreated
  }
} else {
  console.log(`No working memory found for bug ${bugId} - will be created on demand`);
}

Execute appropriate command based on state:

State	Action
DOSSIER, ANALYZE	Spawn AnalysisAgent
VERDICT	Run /bug-plan <bugId>
PLAN_FE, TEST_SPEC	Continue to Validation
VALIDATE, FEATURE_DESIGN	Show plan and await /bug-accept
EXECUTE	Run /bug-accept <bugId>
VERIFY	Run /bug-verify <bugId>
VERIFY_FAIL	Offer re-plan or retry

Option 2: Reset to Previous Phase

Update state file to previous phase:

const previousPhase = getPreviousPhase(currentState.state);
const fieldsToNull = getFieldsToClear(previousPhase);

const newState = {
  ...currentState,
  state: previousPhase,
  ...fieldsToNull
};

await writeStateAtomic(bugId, newState);

Then continue with Option 1.

Option 3: Start Fresh

Run /bug-reset <bugId> --hard then /bug-start <bugId>.

Option 4: Cancel

Do nothing. Report current state and exit.

---

Step 7: Report Resume Status

After resume action completes:

Bug <bugId>: Workflow Resumed

Previous session: wf-<bugId>-<old_session>
New session: wf-<bugId>-<new_session>

Resumed from: <phase>
Current state: <new_state>

Next steps:
- <appropriate next step based on state>

---

Error Handling

State File Corrupted

Error: Cannot read state file for bug <bugId>.

The state file appears corrupted.

Options:
1. Try recovery from backup: /bug-resume <bugId> --from-backup
2. Start fresh: /bug-reset <bugId> --hard && /bug-start <bugId>

Lock Conflict

Warning: Another session may be working on bug <bugId>.

Lock held by: wf-<bugId>-<session>
Acquired: <timestamp>
Expires: <expires>

Options:
1. Resume anyway (take over lock)
2. Wait for other session
3. Force reset: /bug-reset <bugId>

Stale Branch

Warning: Current branch does not match workflow.

Workflow branch: bug/<bugId>-<slug>
Current branch: <current_branch>

Switching to workflow branch...

---

State Helpers

getPreviousPhase()

const phaseOrder = [
  'INIT', 'SCOUT', 'DOSSIER', 'ANALYZE', 'VERDICT',
  'PLAN_FE', 'TEST_SPEC', 'VALIDATE', 'EXECUTE', 'VERIFY', 'CLOSED'
];

function getPreviousPhase(currentPhase) {
  const index = phaseOrder.indexOf(currentPhase);
  if (index <= 0) return 'INIT';
  return phaseOrder[index - 1];
}

calculateAge()

function calculateAge(timestamp) {
  const ms = Date.now() - new Date(timestamp).getTime();
  const hours = Math.floor(ms / (1000 * 60 * 60));
  if (hours < 1) return 'less than 1 hour';
  if (hours < 24) return `${hours} hour(s)`;
  const days = Math.floor(hours / 24);
  return `${days} day(s)`;
}

---

Usage Examples

Resume specific bug

/bug-resume 6312

Bug 6312: Delete favorites folder causes error

Current State: PLAN_FE
Branch: bug/6312-delete-favorites
Last Updated: 2 hours ago

Resuming from PLAN_FE...
Running plan validation...

Scan for all incomplete

/bug-resume

Found 2 incomplete workflow(s):

1. Bug 6312 - PLAN_FE (2 hours ago)
2. Bug 6307 - EXECUTE (1 day ago)

Enter bug ID to resume: 6312

Resume after crash

# Previous session crashed during verification
/bug-resume 6312

Bug 6312 can be resumed from VERIFY.

Options:
1. Resume from checkpoint (re-run verification)
2. Reset to EXECUTE (re-apply changes)
3. Start fresh
4. Cancel

> 1

Resuming verification for bug 6312...

---

Integration with Lock System

The resume command integrates with workflow locking:

1. If lock exists and expired: Take over (normal resume)
2. If lock exists and active: Warn but allow user to proceed
3. If no lock: Create new lock

This ensures that:

• Crashed sessions can be resumed after lock expires (4 hours)
• Users can explicitly take over interrupted workflows
• New sessions get proper locking

---

Notes

• Resume is idempotent - can be run multiple times safely
• State file is the source of truth for workflow progress
• Lock is advisory - user can override if needed
• All resume actions are logged for debugging