Faber Debugger

FABER Debugger Skill

You operate in two modes:

1. Targeted debugging - Analyze a specific problem provided as input
2. Automatic detection - Parse warnings and errors from previous workflow steps

Your key differentiator is maintaining a knowledge base of past issues and solutions in source control, allowing you to:

• Reference similar past issues when diagnosing new ones
• Avoid reinventing solutions for recurring problems
• Build institutional knowledge across projects

You use the claude-sonnet-4-5 model for balanced analysis performance.

Optional Parameters:

• work_id (string): Work item identifier for GitHub logging
• problem (string): Explicit problem description to diagnose (targeted mode)
• phase (string): Focus analysis on specific phase
• step (string): Focus analysis on specific step
• create_spec (boolean): Create specification for complex issues (default: auto-detect)

Invocation Modes:

Mode 1: Targeted Debugging

{
  "run_id": "fractary/claude-plugins/abc123",
  "work_id": "244",
  "problem": "Test suite failing with timeout errors on authentication tests"
}

Mode 2: Automatic Detection

{
  "run_id": "fractary/claude-plugins/abc123",
  "work_id": "244"
}

When problem is omitted, the debugger automatically parses warnings and errors from previous workflow steps.

Step 1: Gather Debug Context

Collect all necessary information for diagnosis.

See workflow/gather-debug-context.md for detailed steps.

Gather:

• Current workflow state (via faber-state skill)
• Event history for the run
• Errors and warnings from step executions
• Relevant artifacts (specs, code changes)
• Explicit problem description (if provided)

Outputs:

• Complete state snapshot
• Aggregated errors and warnings
• Timeline of events

Step 2: Search Knowledge Base

Check if similar issues have been resolved before.

See workflow/search-knowledge-base.md for detailed steps.

Search Strategy:

1. Extract keywords from problem/errors
2. Search knowledge base index by keywords
3. Calculate similarity scores for matching entries
4. Return top 3 relevant past solutions

Outputs:

• Matching knowledge base entries (if any)
• Similarity scores
• Recommended solutions from past issues

Step 3: Analyze Issue

Diagnose the root cause of the problem.

See workflow/diagnose-issue.md for detailed steps.

Analysis Points:

• Error message patterns and their meanings
• State at time of failure
• Related code changes (if applicable)
• Common causes for this type of error
• Knowledge base insights (if matches found)

Outputs:

• Root cause analysis
• Contributing factors
• Confidence level (high/medium/low)

Step 4: Propose Solutions

Generate actionable solutions based on analysis.

See workflow/propose-solution.md for detailed steps.

Solution Generation:

1. If knowledge base match found with high similarity (>0.8):
   • Adapt past solution to current context
   • Include reference to original resolution
2. If no match or low similarity:
   • Generate fresh solution based on analysis
   • Flag as candidate for knowledge base addition

For Each Solution:

• Title and description
• Step-by-step instructions
• FABER continuation command
• Confidence level
• Estimated complexity

Complexity Thresholds:

• Simple (1-2 steps): Direct solution in response
• Moderate (3-5 steps): Detailed solution with command
• Complex (6+ steps): Create specification via fractary-spec

Step 5: Generate Continuation Command

Create the appropriate /fractary-faber:run command for continuing the workflow.

See workflow/generate-continuation.md for detailed steps.

Command Format:

/fractary-faber:run --work-id {work_id} --workflow {workflow} --step {next_step} --prompt "Review the issues and proposed solutions identified by faber-debugger and implement the recommended fixes."

Include:

• Specific step to resume from
• Prompt with context about the diagnosis
• Any relevant flags (--retry, etc.)

Step 6: Log Findings

Document the diagnosis and solutions.

See workflow/log-findings.md for detailed steps.

Log To:

1. Terminal/Session: Complete diagnostic report
2. GitHub Issue (if work_id provided): Summary with solutions
3. Debug Log File: Full context for audit trail

GitHub Comment Format:

## Debugger Analysis

**Status**: {status_emoji} {diagnosis_summary}

### Problem Detected
{problem_description}

### Root Cause Analysis
{root_cause}

### Proposed Solutions
{solutions_list}

### Recommended Next Step
\`\`\`
{faber_run_command}
\`\`\`

---
*Analyzed by faber-debugger at {timestamp}*

Step 7: Update Knowledge Base (On Resolution)

After a solution is successfully applied, add to knowledge base.

Note: This step is triggered by a separate invocation with operation: "learn".

See workflow/update-knowledge-base.md for detailed steps.

Success Response (Issue Diagnosed):

{
  "status": "success",
  "message": "Issue diagnosed - solution proposed",
  "details": {
    "mode": "targeted",
    "problem_summary": "Test timeout in authentication tests",
    "root_cause": "Session cleanup not awaiting async operations",
    "confidence": "high",
    "kb_matches": 2,
    "solutions": [
      {
        "title": "Add await to session cleanup",
        "complexity": "simple",
        "confidence": "high",
        "source": "knowledge_base",
        "kb_entry": "faber-debug-042"
      }
    ],
    "continuation_command": "/fractary-faber:run --work-id 244 --step builder --prompt 'Fix session cleanup async handling as identified by debugger'",
    "spec_created": false,
    "github_comment_url": "https://github.com/org/repo/issues/244#issuecomment-123456"
  }
}

Success Response (No Issues Found):

{
  "status": "success",
  "message": "No errors or warnings detected in workflow execution",
  "details": {
    "mode": "automatic",
    "errors_found": 0,
    "warnings_found": 0,
    "recommendation": "Workflow appears healthy"
  }
}

Warning Response (Issues Diagnosed, Complex Resolution):

{
  "status": "warning",
  "message": "Multiple issues diagnosed - specification created for complex resolution",
  "warnings": [
    "3 distinct issues found requiring coordinated fixes",
    "Estimated 8 implementation steps required"
  ],
  "details": {
    "mode": "automatic",
    "issues_count": 3,
    "solutions": [...],
    "spec_created": true,
    "spec_path": "specs/WORK-00244-debugger-fixes.md",
    "continuation_command": "/fractary-faber:run --work-id 244 --step builder --prompt 'Implement fixes from debugger spec'"
  },
  "warning_analysis": "Multiple issues were found that require careful coordination. A specification has been created to ensure proper implementation order and testing.",
  "suggested_fixes": [
    "Review generated specification before proceeding",
    "Execute fixes in order specified in spec",
    "Run tests after each major fix"
  ]
}

Failure Response (Diagnosis Failed):

{
  "status": "failure",
  "message": "Unable to diagnose issue - insufficient context",
  "errors": [
    "No state file found for run_id",
    "No error events in workflow history"
  ],
  "error_analysis": "The debugger could not find execution context for the specified run. This may indicate the run ID is incorrect or the workflow has not started.",
  "suggested_fixes": [
    "Verify run_id is correct",
    "Check if workflow has started execution",
    "Provide explicit problem description with --problem flag"
  ]
}

Knowledge Base Unavailable:

• Log warning: "Knowledge base not found, performing fresh analysis"
• Continue with standard analysis
• Do not fail - knowledge base is enhancement, not requirement

State Not Found:

• If problem provided: Continue with problem description only
• If no problem: Return failure - cannot do automatic detection without state

GitHub API Errors:

• Log warning about failed comment
• Continue with terminal output
• Do not fail workflow for logging issues

Large Error Context:

• Summarize if over 100 errors
• Group similar errors
• Focus on unique patterns

No Issues Detected:

• Return success with "no issues found"
• This is a valid outcome, not a failure

Knowledge Base Structure

Located at: .fractary/plugins/faber/debugger/knowledge-base/

Directory Layout:

.fractary/plugins/faber/debugger/
├── config.json           # Debugger configuration
├── knowledge-base/
│   ├── index.json        # Searchable index of all entries
│   ├── workflow/         # Workflow execution issues
│   ├── build/            # Build phase issues
│   ├── test/             # Testing issues
│   ├── deploy/           # Deployment issues
│   └── general/          # Uncategorized issues
└── logs/
    └── {date}.log        # Diagnostic session logs

Entry Format:

---
kb_id: faber-debug-{sequence}
category: workflow|build|test|deploy|general
issue_pattern: "Brief pattern description"
symptoms:
  - "Error message pattern 1"
  - "Error message pattern 2"
keywords:
  - keyword1
  - keyword2
root_causes:
  - "Primary cause"
  - "Alternative cause"
solutions:
  - title: "Solution title"
    steps:
      - "Step 1"
      - "Step 2"
    faber_command: "/fractary-faber:run --work-id {id} --step X"
status: verified|unverified|deprecated
created: YYYY-MM-DD
last_used: YYYY-MM-DD
usage_count: N
references:
  - "#issue_number"
---

[Detailed explanation of the issue and solution]

Search Algorithm:

1. Keyword matching (TF-IDF scoring)
2. Error pattern similarity (Levenshtein distance)
3. Category weighting
4. Recency and usage boosting

FABER Manager Integration

The debugger can be invoked:

1. Automatically on step failure:

   [workflow.evaluate]  # Triggers debugger before stopping
   

2. As explicit workflow step:

   [[workflow.evaluate.steps]]
   name = "debug-issues"
   skill = "faber-debugger"
   when = "previous_step_has_warnings"
   

3. Manually via command:

   /fractary-faber:debug --run-id abc123 --problem "Description"
   

Plugin Dependencies

• faber-state: Read workflow state and events
• fractary-work: Post comments to GitHub issues
• fractary-spec: Create specifications for complex issues
• fractary-repo: Access code changes and diffs

Configuration

.fractary/plugins/faber/debugger/config.json:

{
  "enabled": true,
  "knowledge_base_path": ".fractary/plugins/faber/debugger/knowledge-base",
  "auto_detect_errors": true,
  "create_specs_for_complex": true,
  "complex_threshold": 5,
  "log_to_github": true,
  "similarity_threshold": 0.7
}

Files

plugins/faber/skills/faber-debugger/
├── SKILL.md                              # This file
├── workflow/
│   ├── gather-debug-context.md           # Step 1: Context gathering
│   ├── search-knowledge-base.md          # Step 2: KB search
│   ├── diagnose-issue.md                 # Step 3: Root cause analysis
│   ├── propose-solution.md               # Step 4: Solution generation
│   ├── generate-continuation.md          # Step 5: Command generation
│   ├── log-findings.md                   # Step 6: Logging
│   └── update-knowledge-base.md          # Step 7: KB update (on learn)
├── scripts/
│   ├── search-kb.sh                      # Knowledge base search
│   ├── aggregate-errors.sh               # Parse workflow errors
│   ├── generate-command.sh               # Create /fractary-faber:run command
│   ├── log-to-issue.sh                   # Post GitHub comment
│   └── kb-add-entry.sh                   # Add knowledge base entry
└── templates/
    ├── solution-command.template         # Continuation command template
    ├── kb-entry.template                 # Knowledge base entry template
    └── github-comment.template           # GitHub comment template

Debug Logs

Session logs saved to: .fractary/plugins/faber/debugger/logs/{YYYY-MM-DD}.log