What is debug-workflow?

A structured, end-to-end debugging workflow that uses safety gates and an audit trail to ground every step in evidence.

What happens if a mutation occurs without safety gates?

The workflow requires a checkpoint before any mutation; if skipped, actions should not mutate state and require human confirmation.

How is the audit trail created and stored?

Outputs from each step are captured as evidence anchors and written to an audit log during the /audit phase, forming a complete trace.

debug-workflow

npx machina-cli add skill synaptiai/agent-capability-standard/debug-workflow --openclaw

Files (1)

SKILL.md

9.6 KB

Intent

Run the composed workflow debug-workflow using atomic capability skills to systematically debug code changes with full safety and audit capabilities.

Success criteria:

Every step output is grounded with evidence anchors
Safety gates are respected (checkpoint before any mutation)
All issues are traced to root cause with supporting evidence
Final result includes complete audit trail
Rollback pathway documented and verified

Compatible schemas:

reference/workflow_catalog.yaml

Inputs

Parameter	Required	Type	Description
`goal`	Yes	string	The debugging objective (e.g., "identify why tests fail after refactor")
`scope`	Yes	string\|array	Files, directories, or components to investigate
`constraints`	No	object	Hard limits (e.g., time budget, files to exclude, severity threshold)
`prior_context`	No	object	Previous debugging attempts or known information

Procedure

Create checkpoint marker if mutation might occur:
- Create .claude/checkpoint.ok after confirming rollback strategy
Invoke /inspect and store output as inspect_out
- Examine the scope for symptoms, error patterns, recent changes
Invoke /search and store output as search_out
- Find related code, error messages, similar patterns
Invoke /map-relationships and store output as map-relationships_out
- Map dependencies, call graphs, data flows
Invoke /model-schema and store output as model-schema_out
- Model the expected vs actual behavior
Invoke /critique and store output as critique_out
- Critically analyze hypotheses, identify weak points
Invoke /plan and store output as plan_out
- Create remediation plan with verification criteria
Invoke /act-plan and store output as act-plan_out
- Execute the fix with checkpoint protection
Invoke /verify and store output as verify_out
- Confirm fix addresses root cause
Invoke /audit and store output as audit_out
- Record all actions and evidence for audit trail
Invoke /rollback if needed and store output as rollback_out
- Restore previous state if verification fails

Output Contract

Return a structured object:

workflow_id: string  # Unique workflow execution ID
goal: string  # The debugging objective
status: completed | failed | rolled_back
steps:
  inspect_out:
    summary: string
    findings: array[string]
    evidence_anchors: array[string]
  search_out:
    summary: string
    matches: array[string]
    evidence_anchors: array[string]
  map_relationships_out:
    summary: string
    dependencies: array[string]
    evidence_anchors: array[string]
  model_schema_out:
    summary: string
    evidence_anchors: array[string]
  critique_out:
    summary: string
    weaknesses: array[string]
    evidence_anchors: array[string]
  plan_out:
    summary: string
    actions: array[string]
    verification_criteria: array[string]
    evidence_anchors: array[string]
  act_plan_out:
    summary: string
    changes_made: array[string]
    evidence_anchors: array[string]
  verify_out:
    result: PASS | FAIL
    evidence_anchors: array[string]
  audit_out:
    log_path: string
    evidence_anchors: array[string]
  rollback_out:
    executed: boolean
    restore_point: string | null
    evidence_anchors: array[string]
root_cause:
  description: string
  evidence_anchors: array[string]
resolution:
  description: string
  files_changed: array[string]
verification: PASS | FAIL
audit_log_pointer: string  # Path to .claude/audit.log
rollback_available: boolean
rollback_command: string | null
confidence: number  # 0.0-1.0
evidence_anchors: array[string]
assumptions: array[string]

Field Definitions

Field	Type	Description
`workflow_id`	string	Unique identifier for this workflow execution
`status`	enum	Final workflow status
`steps`	object	Summary and evidence from each workflow step
`root_cause`	object	Identified root cause with evidence
`resolution`	object	What was done to fix the issue
`verification`	enum	Final PASS/FAIL after fix applied
`confidence`	number	0.0-1.0 based on evidence quality
`evidence_anchors`	array	All evidence references collected
`assumptions`	array	Explicit assumptions made during debugging

Examples

Example 1: Debug Failing Test After Refactor

Input:

goal: "Identify why user authentication tests fail after handler refactor"
scope:
  - "src/api/handlers/auth.py"
  - "tests/test_auth.py"
constraints:
  max_time: "30m"
  severity: "high"

Output:

workflow_id: "debug_20240115_143022"
goal: "Identify why user authentication tests fail after handler refactor"
status: completed
steps:
  inspect_out:
    summary: "Test failure in test_login_success, line 45"
    findings:
      - "Expected status 200, got 401"
      - "Token validation logic changed in refactor"
    evidence_anchors:
      - "file:tests/test_auth.py:45"
      - "file:src/api/handlers/auth.py:78"
  search_out:
    summary: "Found 3 related token validation patterns"
    matches:
      - "src/api/handlers/auth.py:validate_token"
      - "src/utils/jwt.py:decode_token"
    evidence_anchors:
      - "tool:grep:validate_token"
  map_relationships_out:
    summary: "auth.py depends on jwt.py for token validation"
    dependencies:
      - "auth.py -> jwt.py"
      - "auth.py -> user_model.py"
    evidence_anchors:
      - "tool:ast:import_analysis"
  critique_out:
    summary: "Token validation order changed - signature check now after expiry"
    weaknesses:
      - "Signature validation moved after expiry check, causing premature rejection"
    evidence_anchors:
      - "file:src/api/handlers/auth.py:78-85"
  plan_out:
    summary: "Restore original validation order"
    actions:
      - "Move signature check before expiry check"
    verification_criteria:
      - "test_login_success passes"
      - "No regression in other auth tests"
    evidence_anchors:
      - "file:src/api/handlers/auth.py:78"
  act_plan_out:
    summary: "Reordered validation steps"
    changes_made:
      - "src/api/handlers/auth.py:78-85"
    evidence_anchors:
      - "tool:git:diff"
  verify_out:
    result: PASS
    evidence_anchors:
      - "tool:bash:pytest tests/test_auth.py"
  audit_out:
    log_path: ".claude/audit.log"
    evidence_anchors:
      - "file:.claude/audit.log"
  rollback_out:
    executed: false
    restore_point: "chk_20240115_143000"
    evidence_anchors: []
root_cause:
  description: "Token signature validation was moved after expiry check during refactor, causing valid tokens to be rejected before signature verification"
  evidence_anchors:
    - "file:src/api/handlers/auth.py:78-85"
    - "tool:git:blame"
resolution:
  description: "Restored original validation order: signature check before expiry check"
  files_changed:
    - "src/api/handlers/auth.py"
verification: PASS
audit_log_pointer: ".claude/audit.log"
rollback_available: true
rollback_command: "git stash pop"
confidence: 0.95
evidence_anchors:
  - "file:tests/test_auth.py:45"
  - "file:src/api/handlers/auth.py:78-85"
  - "tool:bash:pytest"
  - "tool:git:diff"
assumptions:
  - "Test environment matches production configuration"
  - "No concurrent changes to auth module"

Evidence pattern: Combined code inspection, git blame for change attribution, test execution for verification.

Verification

Step Completeness: All 10 workflow steps executed with output
Evidence Grounding: Every step output includes evidence_anchors
Checkpoint Created: Mutation steps preceded by checkpoint
Root Cause Identified: root_cause has specific description and evidence
Verification Passed: verify_out.result is PASS before completion
Audit Trail: audit_log_pointer points to valid log file
Rollback Ready: rollback_command documented if changes made

Verification tools: Bash (for test execution), Git (for change verification), Read (for audit log)

Safety Constraints

mutation: true
requires_checkpoint: true
requires_approval: false
risk: high

Capability-specific rules:

NEVER proceed to act-plan without checkpoint and explicit plan
STOP and request clarification if any step produces confidence < 0.3
ALWAYS verify fix before marking workflow complete
Document rollback command before any mutation
Preserve original error state for comparison

Composition Patterns

Commonly follows:

receive - After receiving bug report or error notification
retrieve - After fetching relevant context or logs

Commonly precedes:

summarize - To create debug report for stakeholders
send - To notify team of resolution

Anti-patterns:

Never skip /inspect to jump directly to /plan
Never proceed past /critique without addressing identified weaknesses
Never execute /act-plan without prior /checkpoint
Never mark complete without /verify confirmation

Workflow references:

See reference/workflow_catalog.yaml#debug-workflow for step definitions
See reference/composition_patterns.md#checkpoint-act-verify-rollback for CAVR pattern

Source

git clone https://github.com/synaptiai/agent-capability-standard/blob/main/skills/debug-workflow/SKILL.mdView on GitHub

Overview

debug-workflow executes the Debug Code Change workflow end-to-end with safety gates to ensure traceable debugging. It guides investigators through evidence-grounded steps, from inspection to audit, and records a rollback and verification at closure. This matters for debugging code changes, investigating issues, or performing root-cause analysis with a complete audit trail.

How This Skill Works

The workflow orchestrates atomic capability skills (inspect, search, map-relationships, model-schema, critique, plan, act-plan, verify, audit, rollback) to systematically locate and fix issues. It inserts a checkpoint before mutations, stores outputs as evidence anchors at every step, and requires a documented rollback path if verification fails.

When to Use It

When debugging a recent code change to identify the root cause of a failure
When investigating flaky tests or errors after a refactor
When tracing issues with explicit evidence anchors and dependencies
When an audit trail is required for compliance or reviews
When a rollback may be needed to restore a safe state

Quick Start

Step 1: Define goal, scope, and optional constraints (and prior_context) for the debugging session.
Step 2: Run the 10-step procedure (inspect, search, map-relationships, model-schema, critique, plan, act-plan, verify, audit, rollback) with checkpoint gates.
Step 3: Review audit, confirm success or perform rollback if verification fails.

Best Practices

Define goal, scope, and constraints up front to limit scope and risk
Always create a checkpoint before any mutation and document rollback plans
Capture and store outputs from each step as evidence anchors
Model the expected vs actual behavior to guide remediation
Maintain a complete audit trail of actions, evidence, and decisions

Example Use Cases

Debugging a failing unit test after a feature change, with evidence anchors and rollback plan
Investigating a flaky API call by mapping dependencies and data flows
Root-cause analysis of a performance regression with audit trail
Verifying fixes in a safe environment before deployment, with safety gates
Rolling back a change when verification reveals a broader impact

Frequently Asked Questions

Add this skill to your agents