[V2] Add self-diagnosis when a run fails

[frankbria]

When codeframe work start <task_id> fails, there is no good way to analyze what happened and fix it. Instead, we just get the last error message generated by the agent.

The application upon failure should review the logs of the agent run and make a determination about the next best action to fix the problem and let the agent run to successful completion. Then the user needs CLI commands to be able to either change the task description, "answer" a blocker, or run with a different model/provider.

[traycerai]

Plan

Observations

The codebase has a sophisticated multi-agent system with comprehensive logging, error handling, and quality tracking infrastructure. The codeframe work start <task_id> command is documented in the Golden Path but not yet implemented. The system currently has:

1. Robust logging infrastructure via Python's logging module with detailed error tracking in file:codeframe/agents/lead_agent.py
2. Comprehensive error handling in agent execution loops with retry logic and failure tracking
3. Quality gates and review systems that analyze code and provide detailed feedback
4. Blocker management system for human-in-the-loop interventions
5. Token usage and cost tracking for monitoring LLM API calls
6. Checkpoint and recovery mechanisms for state management

However, there's no self-diagnosis system that analyzes run failures and suggests remediation actions.

Approach

The implementation will add a self-diagnosis system that activates when codeframe work start <task_id> fails. The system will:

1. Capture comprehensive run logs including agent actions, LLM calls, errors, and state transitions
2. Analyze failure patterns using an LLM-powered diagnostic agent to identify root causes
3. Generate actionable recommendations for fixing the issue (change task description, answer blocker, switch model/provider)
4. Provide CLI commands to execute the recommended remediation actions

The approach leverages existing infrastructure (logging, database, LLM providers) and follows the Golden Path CLI-first architecture. The diagnostic agent will be a specialized agent type that analyzes execution logs and provides structured recommendations.

Implementation Steps

1. Create Work Command Group

File: file:codeframe/cli/work_commands.py (new file)

Create a new CLI command group for work-related operations following the pattern in file:codeframe/cli/tasks_commands.py:

• Implement work start <task_id> command that:

  • Validates task exists and is in appropriate state
  • Calls core runtime function to execute task
  • Captures execution logs and errors
  • On failure, automatically triggers self-diagnosis
  • Displays diagnostic results and recommended actions

• Implement work resume <task_id> command for continuing after blocker resolution

• Implement work stop <task_id> command for graceful termination

• Implement work diagnose <task_id> command for manual diagnosis of failed runs

Register the work command group in file:codeframe/cli/__init__.py similar to how other command groups are registered.

2. Create Run Execution Logger

File: file:codeframe/lib/run_logger.py (new file)

Implement a structured logging system specifically for agent runs:

• Create RunLogger class that captures:

  • Task execution timeline (start, steps, completion/failure)
  • Agent actions and decisions
  • LLM API calls with prompts and responses
  • Error messages and stack traces
  • State transitions and database updates
  • Blocker creation events

• Store logs in database table run_logs with fields:

  • id, task_id, run_id, timestamp, log_level, category, message, metadata (JSON)

• Integrate with existing file:codeframe/lib/audit_logger.py for consistency

3. Enhance Task Execution with Run Tracking

Files:

• file:codeframe/agents/lead_agent.py (modify _assign_and_execute_task)
• file:codeframe/agents/worker_agent.py (modify execute_task)

Add run tracking to agent execution:

• Generate unique run_id for each task execution attempt

• Wrap execution in try-catch blocks that log to RunLogger

• Capture detailed error context including:

  • Last successful step before failure
  • Active agent state
  • Recent LLM interactions
  • Database state snapshot

• Store run metadata in new task_runs table:

  • id, task_id, run_id, status, started_at, completed_at, error_message, retry_count

4. Create Diagnostic Agent

File: file:codeframe/agents/diagnostic_agent.py (new file)

Implement a specialized agent for analyzing run failures:

• Create DiagnosticAgent class that:

  • Retrieves run logs for failed task execution
  • Analyzes error patterns and failure modes
  • Uses LLM to identify root causes
  • Generates structured recommendations

• Implement diagnostic analysis categories:

  • Task Description Issues: Ambiguous, incomplete, or contradictory requirements
  • Blocker Issues: Unresolved SYNC blockers preventing progress
  • Model/Provider Issues: Token limits, rate limits, API errors
  • Code Quality Issues: Failing tests, lint errors, review failures
  • Dependency Issues: Missing dependencies, blocked by other tasks
  • Environment Issues: Missing tools, configuration problems

• Return structured DiagnosticReport with:

  • Root cause analysis
  • Severity assessment
  • Recommended remediation actions
  • Specific CLI commands to execute

5. Create Diagnostic Report Model

File: file:codeframe/core/models.py (modify)

Add Pydantic models for diagnostic results:

class RemediationAction(str, Enum):
    UPDATE_TASK_DESCRIPTION = "update_task_description"
    ANSWER_BLOCKER = "answer_blocker"
    CHANGE_MODEL = "change_model"
    CHANGE_PROVIDER = "change_provider"
    RESOLVE_DEPENDENCY = "resolve_dependency"
    FIX_ENVIRONMENT = "fix_environment"
    RETRY_WITH_CONTEXT = "retry_with_context"

class DiagnosticRecommendation(BaseModel):
    action: RemediationAction
    reason: str
    command: str  # CLI command to execute
    parameters: Dict[str, Any]

class DiagnosticReport(BaseModel):
    task_id: int
    run_id: str
    root_cause: str
    failure_category: str
    severity: str  # "critical", "high", "medium", "low"
    recommendations: List[DiagnosticRecommendation]
    log_summary: str
    created_at: datetime

6. Implement Remediation Commands

File: file:codeframe/cli/work_commands.py (extend)

Add commands for executing remediation actions:

• work update-description <task_id> "<new_description>" - Update task description
• work change-model <task_id> <model_name> - Switch to different model (e.g., claude-opus-4)
• work change-provider <task_id> <provider> - Switch provider (future: OpenAI, Gemini)
• work retry <task_id> --with-context - Retry with additional context from diagnostic

These commands should:

• Update task/project configuration
• Clear failed run state
• Optionally trigger automatic retry

7. Create Core Runtime Module

File: file:codeframe/core/runtime.py (new file)

Implement core runtime functions following the Golden Path architecture:

• start_task_run(workspace_id: int, task_id: int) -> str - Start task execution, returns run_id
• stop_task_run(workspace_id: int, task_id: int) -> None - Graceful stop
• resume_task_run(workspace_id: int, task_id: int) -> None - Resume after blocker
• get_run_logs(run_id: str) -> List[Dict] - Retrieve logs for analysis
• diagnose_failure(task_id: int, run_id: str) -> DiagnosticReport - Analyze failure

These functions orchestrate the agent execution and integrate with existing file:codeframe/agents/lead_agent.py multi-agent coordination.

8. Add Database Schema

File: file:codeframe/persistence/database.py (modify)

Add new tables for run tracking and diagnostics:

CREATE TABLE task_runs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id INTEGER NOT NULL,
    run_id TEXT UNIQUE NOT NULL,
    status TEXT NOT NULL,  -- 'running', 'completed', 'failed'
    started_at TIMESTAMP NOT NULL,
    completed_at TIMESTAMP,
    error_message TEXT,
    retry_count INTEGER DEFAULT 0,
    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE TABLE run_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    run_id TEXT NOT NULL,
    task_id INTEGER NOT NULL,
    timestamp TIMESTAMP NOT NULL,
    log_level TEXT NOT NULL,  -- 'DEBUG', 'INFO', 'WARNING', 'ERROR'
    category TEXT NOT NULL,  -- 'agent_action', 'llm_call', 'error', 'state_change'
    message TEXT NOT NULL,
    metadata TEXT,  -- JSON
    FOREIGN KEY (run_id) REFERENCES task_runs(run_id),
    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE TABLE diagnostic_reports (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id INTEGER NOT NULL,
    run_id TEXT NOT NULL,
    root_cause TEXT NOT NULL,
    failure_category TEXT NOT NULL,
    severity TEXT NOT NULL,
    recommendations TEXT NOT NULL,  -- JSON array
    log_summary TEXT,
    created_at TIMESTAMP NOT NULL,
    FOREIGN KEY (task_id) REFERENCES tasks(id),
    FOREIGN KEY (run_id) REFERENCES task_runs(run_id)
);

Add repository methods in file:codeframe/persistence/repositories/ for CRUD operations on these tables.

9. Integrate with Existing Error Handling

Files:

• file:codeframe/agents/lead_agent.py (modify _assign_and_execute_task, _execute_coordination_loop)
• file:codeframe/agents/worker_agent.py (modify error handling)

Enhance existing error handling to:

• Log all exceptions to RunLogger
• Store error context in task_runs table
• Automatically trigger diagnosis on task failure
• Emit WebSocket events for diagnostic completion
• Update task status to include diagnostic information

10. Add CLI Output Formatting

File: file:codeframe/cli/work_commands.py (extend)

Implement rich console output for diagnostic results:

• Display diagnostic report in structured format using Rich library
• Show root cause analysis with color-coded severity
• List recommendations with executable commands
• Provide interactive prompts for executing remediation actions
• Show progress indicators during diagnosis

Example output:

❌ Task #42 execution failed

🔍 Diagnosis Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Root Cause: Task description is ambiguous about authentication method
Category: Task Description Issues
Severity: HIGH

Recommendations:
  1. 🔧 Update task description to clarify requirements
     Command: codeframe work update-description 42 "Implement JWT-based authentication..."
     
  2. 🤖 Switch to more capable model for complex task
     Command: codeframe work change-model 42 claude-opus-4
     
  3. 🔄 Retry with additional context
     Command: codeframe work retry 42 --with-context

Execute recommendation? [1/2/3/n]:

11. Add WebSocket Events

File: file:codeframe/ui/websocket_broadcasts.py (modify)

Add WebSocket events for real-time diagnostic updates:

• diagnostic_started - When diagnosis begins
• diagnostic_completed - When diagnosis finishes with recommendations
• remediation_applied - When user executes a remediation action

This allows the dashboard to show diagnostic progress in real-time.

12. Update Documentation

Files:

• file:docs/CLI_WIREFRAME.md (update work commands section)
• file:docs/GOLDEN_PATH.md (update step 4 with diagnosis flow)
• file:README.md (add work commands to CLI section)

Document the new self-diagnosis feature:

• Add work command examples
• Explain diagnostic process
• Show remediation workflows
• Include troubleshooting guide

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as CLI (work_commands.py)
    participant Runtime as Core Runtime
    participant LeadAgent
    participant WorkerAgent
    participant RunLogger
    participant DiagnosticAgent
    participant DB as Database

    User->>CLI: codeframe work start 42
    CLI->>Runtime: start_task_run(workspace_id, 42)
    Runtime->>DB: Create task_run record
    DB-->>Runtime: run_id
    Runtime->>LeadAgent: assign_and_execute_task(task)
    LeadAgent->>WorkerAgent: execute_task(task)
    
    WorkerAgent->>RunLogger: Log agent actions
    RunLogger->>DB: Store run_logs
    
    WorkerAgent--xLeadAgent: Task execution fails
    LeadAgent->>RunLogger: Log error with context
    RunLogger->>DB: Store error logs
    LeadAgent->>DB: Update task_run status=failed
    
    LeadAgent->>Runtime: Execution failed
    Runtime->>DiagnosticAgent: diagnose_failure(task_id, run_id)
    DiagnosticAgent->>DB: Retrieve run_logs
    DB-->>DiagnosticAgent: Log entries
    DiagnosticAgent->>DiagnosticAgent: Analyze with LLM
    DiagnosticAgent->>DB: Store diagnostic_report
    DiagnosticAgent-->>Runtime: DiagnosticReport
    
    Runtime-->>CLI: Failure + DiagnosticReport
    CLI->>User: Display diagnostic results
    CLI->>User: Show remediation commands
    
    User->>CLI: codeframe work update-description 42 "..."
    CLI->>DB: Update task description
    CLI->>User: ✓ Task updated
    
    User->>CLI: codeframe work retry 42
    CLI->>Runtime: start_task_run(workspace_id, 42)
    Note over Runtime: Retry with updated context

Loading

Key Design Decisions

1. LLM-Powered Diagnosis: Use Claude to analyze logs and identify root causes, leveraging the same AI capabilities that power the agents
2. Structured Recommendations: Return actionable CLI commands rather than generic advice
3. Automatic Triggering: Diagnosis runs automatically on failure, but can also be manually invoked
4. Database-Backed Logging: Store all run logs in SQLite for persistence and analysis
5. CLI-First: Follow Golden Path architecture with CLI as primary interface
6. Incremental Remediation: Allow users to apply fixes one at a time and retry
7. Integration with Existing Systems: Leverage existing blocker, quality gate, and agent infrastructure

Dependencies

• Existing: file:codeframe/agents/lead_agent.py, file:codeframe/agents/worker_agent.py
• Existing: file:codeframe/persistence/database.py, file:codeframe/core/models.py
• Existing: file:codeframe/cli/__init__.py, file:codeframe/cli/helpers.py
• Existing: file:codeframe/providers/sdk_client.py for LLM calls
• New: Rich library for CLI formatting (already in dependencies)

Testing Strategy

1. Unit Tests: Test diagnostic agent analysis logic with mock logs
2. Integration Tests: Test full work command flow with real agent execution
3. E2E Tests: Test complete failure → diagnosis → remediation → retry workflow
4. Failure Scenario Tests: Create specific failure scenarios (ambiguous task, blocker, model error) and verify correct diagnosis

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a sophisticated multi-agent system with comprehensive logging, error handling, and quality tracking infrastructure. The `codeframe work start <task_id>` command is documented in the Golden Path but not yet implemented. The system currently has:

1. **Robust logging infrastructure** via Python's logging module with detailed error tracking in `file:codeframe/agents/lead_agent.py`
2. **Comprehensive error handling** in agent execution loops with retry logic and failure tracking
3. **Quality gates and review systems** that analyze code and provide detailed feedback
4. **Blocker management system** for human-in-the-loop interventions
5. **Token usage and cost tracking** for monitoring LLM API calls
6. **Checkpoint and recovery mechanisms** for state management

However, there's no self-diagnosis system that analyzes run failures and suggests remediation actions.

## Approach

The implementation will add a **self-diagnosis system** that activates when `codeframe work start <task_id>` fails. The system will:

1. **Capture comprehensive run logs** including agent actions, LLM calls, errors, and state transitions
2. **Analyze failure patterns** using an LLM-powered diagnostic agent to identify root causes
3. **Generate actionable recommendations** for fixing the issue (change task description, answer blocker, switch model/provider)
4. **Provide CLI commands** to execute the recommended remediation actions

The approach leverages existing infrastructure (logging, database, LLM providers) and follows the Golden Path CLI-first architecture. The diagnostic agent will be a specialized agent type that analyzes execution logs and provides structured recommendations.

## Implementation Steps

### 1. Create Work Command Group

**File**: `file:codeframe/cli/work_commands.py` (new file)

Create a new CLI command group for work-related operations following the pattern in `file:codeframe/cli/tasks_commands.py`:

- Implement `work start <task_id>` command that:
  - Validates task exists and is in appropriate state
  - Calls core runtime function to execute task
  - Captures execution logs and errors
  - On failure, automatically triggers self-diagnosis
  - Displays diagnostic results and recommended actions
  
- Implement `work resume <task_id>` command for continuing after blocker resolution
- Implement `work stop <task_id>` command for graceful termination
- Implement `work diagnose <task_id>` command for manual diagnosis of failed runs

Register the work command group in `file:codeframe/cli/__init__.py` similar to how other command groups are registered.

### 2. Create Run Execution Logger

**File**: `file:codeframe/lib/run_logger.py` (new file)

Implement a structured logging system specifically for agent runs:

- Create `RunLogger` class that captures:
  - Task execution timeline (start, steps, completion/failure)
  - Agent actions and decisions
  - LLM API calls with prompts and responses
  - Error messages and stack traces
  - State transitions and database updates
  - Blocker creation events
  
- Store logs in database table `run_logs` with fields:
  - `id`, `task_id`, `run_id`, `timestamp`, `log_level`, `category`, `message`, `metadata` (JSON)
  
- Integrate with existing `file:codeframe/lib/audit_logger.py` for consistency

### 3. Enhance Task Execution with Run Tracking

**Files**: 
- `file:codeframe/agents/lead_agent.py` (modify `_assign_and_execute_task`)
- `file:codeframe/agents/worker_agent.py` (modify `execute_task`)

Add run tracking to agent execution:

- Generate unique `run_id` for each task execution attempt
- Wrap execution in try-catch blocks that log to `RunLogger`
- Capture detailed error context including:
  - Last successful step before failure
  - Active agent state
  - Recent LLM interactions
  - Database state snapshot
  
- Store run metadata in new `task_runs` table:
  - `id`, `task_id`, `run_id`, `status`, `started_at`, `completed_at`, `error_message`, `retry_count`

### 4. Create Diagnostic Agent

**File**: `file:codeframe/agents/diagnostic_agent.py` (new file)

Implement a specialized agent for analyzing run failures:

- Create `DiagnosticAgent` class that:
  - Retrieves run logs for failed task execution
  - Analyzes error patterns and failure modes
  - Uses LLM to identify root causes
  - Generates structured recommendations
  
- Implement diagnostic analysis categories:
  - **Task Description Issues**: Ambiguous, incomplete, or contradictory requirements
  - **Blocker Issues**: Unresolved SYNC blockers preventing progress
  - **Model/Provider Issues**: Token limits, rate limits, API errors
  - **Code Quality Issues**: Failing tests, lint errors, review failures
  - **Dependency Issues**: Missing dependencies, blocked by other tasks
  - **Environment Issues**: Missing tools, configuration problems
  
- Return structured `DiagnosticReport` with:
  - Root cause analysis
  - Severity assessment
  - Recommended remediation actions
  - Specific CLI commands to execute

### 5. Create Diagnostic Report Model

**File**: `file:codeframe/core/models.py` (modify)

Add Pydantic models for diagnostic results:

```python
class RemediationAction(str, Enum):
    UPDATE_TASK_DESCRIPTION = "update_task_description"
    ANSWER_BLOCKER = "answer_blocker"
    CHANGE_MODEL = "change_model"
    CHANGE_PROVIDER = "change_provider"
    RESOLVE_DEPENDENCY = "resolve_dependency"
    FIX_ENVIRONMENT = "fix_environment"
    RETRY_WITH_CONTEXT = "retry_with_context"

class DiagnosticRecommendation(BaseModel):
    action: RemediationAction
    reason: str
    command: str  # CLI command to execute
    parameters: Dict[str, Any]

class DiagnosticReport(BaseModel):
    task_id: int
    run_id: str
    root_cause: str
    failure_category: str
    severity: str  # "critical", "high", "medium", "low"
    recommendations: List[DiagnosticRecommendation]
    log_summary: str
    created_at: datetime
```

### 6. Implement Remediation Commands

**File**: `file:codeframe/cli/work_commands.py` (extend)

Add commands for executing remediation actions:

- `work update-description <task_id> "<new_description>"` - Update task description
- `work change-model <task_id> <model_name>` - Switch to different model (e.g., claude-opus-4)
- `work change-provider <task_id> <provider>` - Switch provider (future: OpenAI, Gemini)
- `work retry <task_id> --with-context` - Retry with additional context from diagnostic

These commands should:
- Update task/project configuration
- Clear failed run state
- Optionally trigger automatic retry

### 7. Create Core Runtime Module

**File**: `file:codeframe/core/runtime.py` (new file)

Implement core runtime functions following the Golden Path architecture:

- `start_task_run(workspace_id: int, task_id: int) -> str` - Start task execution, returns run_id
- `stop_task_run(workspace_id: int, task_id: int) -> None` - Graceful stop
- `resume_task_run(workspace_id: int, task_id: int) -> None` - Resume after blocker
- `get_run_logs(run_id: str) -> List[Dict]` - Retrieve logs for analysis
- `diagnose_failure(task_id: int, run_id: str) -> DiagnosticReport` - Analyze failure

These functions orchestrate the agent execution and integrate with existing `file:codeframe/agents/lead_agent.py` multi-agent coordination.

### 8. Add Database Schema

**File**: `file:codeframe/persistence/database.py` (modify)

Add new tables for run tracking and diagnostics:

```sql
CREATE TABLE task_runs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id INTEGER NOT NULL,
    run_id TEXT UNIQUE NOT NULL,
    status TEXT NOT NULL,  -- 'running', 'completed', 'failed'
    started_at TIMESTAMP NOT NULL,
    completed_at TIMESTAMP,
    error_message TEXT,
    retry_count INTEGER DEFAULT 0,
    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE TABLE run_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    run_id TEXT NOT NULL,
    task_id INTEGER NOT NULL,
    timestamp TIMESTAMP NOT NULL,
    log_level TEXT NOT NULL,  -- 'DEBUG', 'INFO', 'WARNING', 'ERROR'
    category TEXT NOT NULL,  -- 'agent_action', 'llm_call', 'error', 'state_change'
    message TEXT NOT NULL,
    metadata TEXT,  -- JSON
    FOREIGN KEY (run_id) REFERENCES task_runs(run_id),
    FOREIGN KEY (task_id) REFERENCES tasks(id)
);

CREATE TABLE diagnostic_reports (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    task_id INTEGER NOT NULL,
    run_id TEXT NOT NULL,
    root_cause TEXT NOT NULL,
    failure_category TEXT NOT NULL,
    severity TEXT NOT NULL,
    recommendations TEXT NOT NULL,  -- JSON array
    log_summary TEXT,
    created_at TIMESTAMP NOT NULL,
    FOREIGN KEY (task_id) REFERENCES tasks(id),
    FOREIGN KEY (run_id) REFERENCES task_runs(run_id)
);
```

Add repository methods in `file:codeframe/persistence/repositories/` for CRUD operations on these tables.

### 9. Integrate with Existing Error Handling

**Files**:
- `file:codeframe/agents/lead_agent.py` (modify `_assign_and_execute_task`, `_execute_coordination_loop`)
- `file:codeframe/agents/worker_agent.py` (modify error handling)

Enhance existing error handling to:

- Log all exceptions to `RunLogger`
- Store error context in `task_runs` table
- Automatically trigger diagnosis on task failure
- Emit WebSocket events for diagnostic completion
- Update task status to include diagnostic information

### 10. Add CLI Output Formatting

**File**: `file:codeframe/cli/work_commands.py` (extend)

Implement rich console output for diagnostic results:

- Display diagnostic report in structured format using Rich library
- Show root cause analysis with color-coded severity
- List recommendations with executable commands
- Provide interactive prompts for executing remediation actions
- Show progress indicators during diagnosis

Example output:
```
❌ Task #42 execution failed

🔍 Diagnosis Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Root Cause: Task description is ambiguous about authentication method
Category: Task Description Issues
Severity: HIGH

Recommendations:
  1. 🔧 Update task description to clarify requirements
     Command: codeframe work update-description 42 "Implement JWT-based authentication..."
     
  2. 🤖 Switch to more capable model for complex task
     Command: codeframe work change-model 42 claude-opus-4
     
  3. 🔄 Retry with additional context
     Command: codeframe work retry 42 --with-context

Execute recommendation? [1/2/3/n]:
```

### 11. Add WebSocket Events

**File**: `file:codeframe/ui/websocket_broadcasts.py` (modify)

Add WebSocket events for real-time diagnostic updates:

- `diagnostic_started` - When diagnosis begins
- `diagnostic_completed` - When diagnosis finishes with recommendations
- `remediation_applied` - When user executes a remediation action

This allows the dashboard to show diagnostic progress in real-time.

### 12. Update Documentation

**Files**:
- `file:docs/CLI_WIREFRAME.md` (update work commands section)
- `file:docs/GOLDEN_PATH.md` (update step 4 with diagnosis flow)
- `file:README.md` (add work commands to CLI section)

Document the new self-diagnosis feature:

- Add work command examples
- Explain diagnostic process
- Show remediation workflows
- Include troubleshooting guide

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as CLI (work_commands.py)
    participant Runtime as Core Runtime
    participant LeadAgent
    participant WorkerAgent
    participant RunLogger
    participant DiagnosticAgent
    participant DB as Database

    User->>CLI: codeframe work start 42
    CLI->>Runtime: start_task_run(workspace_id, 42)
    Runtime->>DB: Create task_run record
    DB-->>Runtime: run_id
    Runtime->>LeadAgent: assign_and_execute_task(task)
    LeadAgent->>WorkerAgent: execute_task(task)
    
    WorkerAgent->>RunLogger: Log agent actions
    RunLogger->>DB: Store run_logs
    
    WorkerAgent--xLeadAgent: Task execution fails
    LeadAgent->>RunLogger: Log error with context
    RunLogger->>DB: Store error logs
    LeadAgent->>DB: Update task_run status=failed
    
    LeadAgent->>Runtime: Execution failed
    Runtime->>DiagnosticAgent: diagnose_failure(task_id, run_id)
    DiagnosticAgent->>DB: Retrieve run_logs
    DB-->>DiagnosticAgent: Log entries
    DiagnosticAgent->>DiagnosticAgent: Analyze with LLM
    DiagnosticAgent->>DB: Store diagnostic_report
    DiagnosticAgent-->>Runtime: DiagnosticReport
    
    Runtime-->>CLI: Failure + DiagnosticReport
    CLI->>User: Display diagnostic results
    CLI->>User: Show remediation commands
    
    User->>CLI: codeframe work update-description 42 "..."
    CLI->>DB: Update task description
    CLI->>User: ✓ Task updated
    
    User->>CLI: codeframe work retry 42
    CLI->>Runtime: start_task_run(workspace_id, 42)
    Note over Runtime: Retry with updated context
```

## Key Design Decisions

1. **LLM-Powered Diagnosis**: Use Claude to analyze logs and identify root causes, leveraging the same AI capabilities that power the agents
2. **Structured Recommendations**: Return actionable CLI commands rather than generic advice
3. **Automatic Triggering**: Diagnosis runs automatically on failure, but can also be manually invoked
4. **Database-Backed Logging**: Store all run logs in SQLite for persistence and analysis
5. **CLI-First**: Follow Golden Path architecture with CLI as primary interface
6. **Incremental Remediation**: Allow users to apply fixes one at a time and retry
7. **Integration with Existing Systems**: Leverage existing blocker, quality gate, and agent infrastructure

## Dependencies

- Existing: `file:codeframe/agents/lead_agent.py`, `file:codeframe/agents/worker_agent.py`
- Existing: `file:codeframe/persistence/database.py`, `file:codeframe/core/models.py`
- Existing: `file:codeframe/cli/__init__.py`, `file:codeframe/cli/helpers.py`
- Existing: `file:codeframe/providers/sdk_client.py` for LLM calls
- New: Rich library for CLI formatting (already in dependencies)

## Testing Strategy

1. **Unit Tests**: Test diagnostic agent analysis logic with mock logs
2. **Integration Tests**: Test full work command flow with real agent execution
3. **E2E Tests**: Test complete failure → diagnosis → remediation → retry workflow
4. **Failure Scenario Tests**: Create specific failure scenarios (ambiguous task, blocker, model error) and verify correct diagnosis

---

Execution Information

Branch: main
Commit: 81fdeee

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.