issue-logging-during-ralph-execution

Issue Logging During Ralph Execution

This skill provides structured guidance for logging issues that occur during Ralph autonomous execution, ensuring comprehensive data for revise reports.

When to Log Issues

Always log when:

• Quality gates fail
• Manual intervention is required
• A task step is confusing or unclear
• Skills don't execute as expected
• Configuration is missing or incorrect
• External tools/services fail
• Workflows have bugs or broken instructions

Log even if resolved:

• You found a workaround
• The issue was temporary
• You manually fixed something
• The problem was environmental

Issue Categories

Ralph Systems

• Core execution engine problems
• Quality gate configuration issues
• Beads integration failures
• Performance bottlenecks
• State management problems

Workflows & Process

• Unclear or broken instructions
• Missing workflow steps
• Process flow problems
• Coordination failures
• Resource gathering issues

Code Rules & Documentation

• Missing validation rules
• Documentation inconsistencies
• Template problems
• Reference documentation gaps
• API documentation issues

Skills & Prompts

• Skill execution failures
• Prompt clarity problems
• Error handling gaps
• Integration issues between skills
• Missing edge case handling

Infrastructure & Tooling

• Missing dependencies
• Environment configuration problems
• CLI command failures
• File system issues
• External service problems

Logging Format

Required Fields:

{
  "timestamp": "2026-01-10T14:30:00Z",
  "category": "ralph_systems",
  "severity": "medium",
  "title": "Quality gate configuration incorrect",
  "description": "The lint command in quality-gates.json was using 'eslint' but project uses 'npm run lint'",
  "symptoms": "Command not found error when running quality gates",
  "workaround": "Manually updated the quality-gates.json file to use correct command",
  "context": "Executing Task 2: Add TypeScript types, quality gate stage"
}

Severity Guidelines:

• Critical: Blocks execution completely, data loss risk
• High: Significant manual intervention required
• Medium: Workaround needed, slows progress
• Low: Minor inconvenience, cosmetic issue

Common Scenarios & Examples

Quality Gate Failures

{
  "timestamp": "2026-01-10T15:45:00Z",
  "category": "ralph_systems", 
  "severity": "high",
  "title": "TypeScript quality gate fails with module resolution error",
  "description": "tsc command fails due to missing path mapping in tsconfig.json",
  "symptoms": "error TS2307: Cannot find module '@types/node'",
  "workaround": "Manually installed missing types package and re-ran typecheck",
  "context": "Task 3 quality gate validation"
}

Workflow Confusion

{
  "timestamp": "2026-01-10T16:20:00Z",
  "category": "workflows_process",
  "severity": "medium", 
  "title": "Unclear instruction in skill execution",
  "description": "Step 2 of database-migration skill says 'configure connection' but doesn't specify which config file",
  "symptoms": "Spent 15 minutes searching for correct config location",
  "workaround": "Found config in .env file after checking multiple locations",
  "context": "Executing skill: database-migration"
}

Missing Infrastructure

{
  "timestamp": "2026-01-10T17:10:00Z",
  "category": "infrastructure_tooling",
  "severity": "high",
  "title": "Required CLI tool not installed",
  "description": "Skill requires 'jq' for JSON processing but tool not available in environment",
  "symptoms": "Command not found: jq",
  "workaround": "Rewrote JSON processing using native shell commands",
  "context": "Skill execution: json-config-parser"
}

Integration with Execution Loop

Where to add logging:

1. Before task execution: Log if task setup fails
2. During skill execution: Log when skills don't work as expected
3. Quality gate stage: Log all failures and manual interventions
4. State management: Log when Beads operations fail
5. After task completion: Log if success required unusual steps

Logging Implementation:

• Append to revise-issues.json in execution output directory
• Use .devagent/plugins/ralph/output/revise-issues.json as the canonical example
• Use atomic writes to prevent corruption
• Include timestamps for chronological analysis
• Validate JSON structure before writing

Error Handling for Logging

If logging fails:

• Don't let logging failures stop execution
• Fallback to simple Beads comment with issue summary
• Note logging failure in task comments
• Continue with primary execution objectives

Best Practices:

• Log immediately when issues occur
• Include enough context for later analysis
• Be specific about what went wrong
• Document successful workarounds
• Log even small issues that might indicate patterns