bug-reset

Skill: bug-reset

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
• V3 Integration Points
• Description
• Execution Flow
  • Step 1: Parse Arguments
  • Step 2: Validate State File Exists
  • Step 3: Show Current State
  • Step 3.5: Force Release Workflow Lock (V3 - NEW)
  • Step 3.75: Log Workflow Reset (V3)
  • Step 4: Execute Reset
  • Step 5: Final Report
• Error Handling
• State Order Reference
• Notes

Metadata

• Command: /bug-reset <bug_id>
• Aliases: bug reset, bugreset
• Args:
  • bug_id (required) - Bugzilla bug ID
  • --to <state> (optional) - Target state to reset to (SCOUT, DOSSIER, ANALYZE, PLAN_FE, TEST_SPEC, EXECUTE)
  • --hard (optional) - Also delete dossier markdown file
• Examples:
  • /bug-reset 2210 - Reset workflow, keep dossier
  • /bug-reset 2210 --to PLAN_FE - Reset to re-run from planning
  • /bug-reset 2210 --hard - Delete everything and start fresh

V3 Integration Points

This command integrates with the following V3 systems:

System	Reference	Purpose
Workflow Lock	${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/workflow-lock.md	Prevent duplicate workflows
Atomic State IO	${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/state-io.md	Safe state read/write
Structured Logging	${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/logger.md	Event tracking

All state writes MUST use atomic protocol. Lock MUST be force-released before reset. WORKFLOW_RESET event MUST be logged.

Description

Resets a bug's workflow state to allow re-running the workflow from the beginning or from a specific state.

Use cases:

• Re-run workflow after agent changes
• Retry from a specific step after failure
• Start fresh after testing

---

Execution Flow

Step 1: Parse Arguments

Extract from user input:

• bugId - The bug ID (required)
• --to <state> - Target state to reset to (optional)
• --hard - Whether to delete dossier too (optional)

// Accepts:
// - "2210"
// - "2210 --to PLAN_FE"
// - "2210 --hard"
// - "bug/2210" -> extracts "2210"

const bugIdMatch = input.match(/(\d+)/);
const toMatch = input.match(/--to\s+(\w+)/i);
const hardFlag = input.includes('--hard');

Step 2: Validate State File Exists

Read <paths.stateDir> from project config (default: .bugflow) / <bugId>.json:

If not exists:

No workflow found for bug <bugId>.

Nothing to reset. Run `/bug-start <bugId>` to begin.

If exists: Continue to Step 3.

Step 3: Show Current State

Display current workflow state before reset:

Bug <bugId> current state:
- State: <current_state>
- Branch: <branch>
- Verdict: <verdict>
- Last action: <last_action>

Step 3.5: Force Release Workflow Lock (V3 - NEW)

IMPORTANT: Before any reset operation, force release the workflow lock.

See: ${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/workflow-lock.md for full implementation.

Steps:

1. Check if <paths.stateDir> from project config / <bugId>.lock exists
2. If exists:
   • Read lock file to log the release
   • Delete lock file unconditionally
   • Log LOCK_FORCE_RELEASE event
3. If not exists: Continue (no lock to release)

Implementation:

STATE_DIR="<paths.stateDir from project config, default: .bugflow>"
LOCK_PATH="${STATE_DIR}/<bugId>.lock"
if [ -f "$LOCK_PATH" ]; then
  echo "Force releasing workflow lock for bug <bugId>..."
  rm -f "$LOCK_PATH"
fi

Log Event:

{
  "event": "LOCK_FORCE_RELEASE",
  "details": {
    "reason": "bug-reset command",
    "previous_session": "<sessionId from lock>",
    "previous_phase": "<phase from lock>"
  }
}

Report:

Lock released for bug <bugId>
Previous session: wf-<bugId>-<session>
Previous phase: <phase>

Step 3.75: Log Workflow Reset (V3)

See: ${CLAUDE_PLUGIN_ROOT}/infrastructure/lib/logger.md for full logging utilities.

Log WORKFLOW_RESET event:

{
  "timestamp": "{{ISO}}",
  "bugId": "{{bugId}}",
  "event": "WORKFLOW_RESET",
  "phase": null,
  "agent": null,
  "details": {
    "previous_state": "{{previousState}}",
    "reset_type": "hard" | "soft" | "to-state",
    "target_state": "{{targetState or null}}",
    "files_deleted": {{deletedFilesList}},
    "files_preserved": {{preservedFilesList}}
  }
}

Append to existing log file if exists:

• Path: <paths.stateDir> from project config (default: .bugflow) / _logs/<bugId>.log.json
• If log file doesn't exist (hard reset before any logging), skip logging

Reset Type Mapping:

• --hard flag → reset_type: "hard"
• --to <state> flag → reset_type: "to-state"
• No flags (default) → reset_type: "soft"

Step 4: Execute Reset

Option A: --hard flag

Delete both state file, dossier, AND lock:

STATE_DIR="<paths.stateDir from project config, default: .bugflow>"
DOSSIER_DIR="<paths.dossierDir from project config, default: docs/bugflow>"
rm -f "${STATE_DIR}/<bugId>.json"
rm -f "${STATE_DIR}/<bugId>.lock"
rm -f "${DOSSIER_DIR}/bug-<bugId>.md"

Report:

Bug <bugId> workflow completely reset.
- Deleted: <paths.stateDir>/<bugId>.json
- Deleted: <paths.dossierDir>/bug-<bugId>.md

Run `/bug-start <bugId>` to begin fresh.

Option B: --to <state> flag

Reset to specific state by modifying state file:

Valid states: SCOUT, DOSSIER, ANALYZE, PLAN_FE, TEST_SPEC, EXECUTE

Fields to clear based on target state:

Target State	Clear These Fields
SCOUT	analysisResult, planResult, testSpec, validationResult, verificationResult
DOSSIER	analysisResult, planResult, testSpec, validationResult, verificationResult
ANALYZE	planResult, testSpec, validationResult, verificationResult
PLAN_FE	testSpec, validationResult, verificationResult
TEST_SPEC	validationResult, verificationResult
EXECUTE	verificationResult

Update state file:

{
  ...existing,
  "state": "<target_state>",
  // cleared fields set to null
  "executionLog": [
    ...existing,
    { "timestamp": "<ISO>", "action": "RESET", "result": "success", "resetTo": "<target_state>" }
  ],
  "updatedAt": "<ISO>"
}

Report:

Bug <bugId> reset to <target_state>.

Cleared: <list of cleared fields>
Preserved: <list of preserved fields>

Run `/bug-start <bugId>` to continue from <target_state>.

Option C: No flags (default)

Delete state file and lock, keep dossier for reference:

STATE_DIR="<paths.stateDir from project config, default: .bugflow>"
rm -f "${STATE_DIR}/<bugId>.json"
rm -f "${STATE_DIR}/<bugId>.lock"

Report:

Bug <bugId> workflow reset.

- Deleted: <paths.stateDir>/<bugId>.json
- Deleted: <paths.stateDir>/<bugId>.lock (if existed)
- Preserved: <paths.dossierDir>/bug-<bugId>.md (for reference)

Run `/bug-start <bugId>` to begin fresh.
The existing dossier will be updated with new data.

Step 5: Final Report

Show what was reset and next steps:

┌─────────────────────────────────────────────────────────────┐
│ Bug <bugId> Reset Complete                                  │
├─────────────────────────────────────────────────────────────┤
│ Previous state: <old_state>                                 │
│ New state: <new_state or INIT>                              │
│ Files deleted: <count>                                      │
│ Files preserved: <count>                                    │
├─────────────────────────────────────────────────────────────┤
│ Next: Run `/bug-start <bugId>` to continue                  │
└─────────────────────────────────────────────────────────────┘

---

Error Handling

Invalid State

Error: Invalid state '<state>'

Valid states: SCOUT, DOSSIER, ANALYZE, PLAN_FE, TEST_SPEC, EXECUTE

Example: /bug-reset 2210 --to PLAN_FE

No Bug ID

Error: Bug ID required

Usage: /bug-reset <bug_id> [--to <state>] [--hard]

Examples:
  /bug-reset 2210
  /bug-reset 2210 --to PLAN_FE
  /bug-reset 2210 --hard

State File Read Error

Error: Cannot read state file for bug <bugId>

File: <paths.stateDir>/<bugId>.json
Error: <error message>

Try `/bug-reset <bugId> --hard` to force reset.

---

State Order Reference

States in workflow order (for --to validation):

1. INIT
2. SCOUT
3. DOSSIER
4. ANALYZE
5. VERDICT
6. PLAN_FE
7. TEST_SPEC
8. VALIDATE
9. EXECUTE
10. VERIFY
11. CLOSED

Only states 2-9 are valid reset targets (can't reset to INIT via --to, use default instead; can't reset to terminal states).

---

Notes

• Default behavior (no flags) is the safest - preserves dossier for reference
• --hard is destructive - use when you want a completely fresh start
• --to is surgical - use when you want to re-run specific steps
• Branch is NOT deleted - manual git branch cleanup may be needed
• Slack notifications are NOT sent for reset operations