Ralph Calibrate

Run calibration checks to ensure code and agent behavior align with planning intentions.

Execution Instructions

When this skill is invoked, check the ARGUMENTS provided:

If argument is intention:

Run intention drift analysis to verify completed subtasks align with planning chain (Vision → Story → Task → Subtask).

Prerequisites check first:

1. Look for subtasks.json in the project root
2. If not found, output a helpful message and exit gracefully:

   "No subtasks.json found. Nothing to analyze for intention drift.

   To run intention drift analysis, create a subtasks.json file with completed subtasks that have commitHash values."

3. If found but no completed subtasks have commitHash, output:

   "No completed subtasks with commitHash found. Nothing to analyze."

If prerequisites are met, follow: @context/workflows/ralph/calibration/intention-drift.md

If argument is technical:

Run technical quality analysis to check code quality patterns.

Prerequisites check first:

1. Look for subtasks.json in the project root
2. If not found, output a helpful message and exit gracefully:

   "No subtasks.json found. Nothing to analyze for technical drift.

   To run technical drift analysis, create a subtasks.json file with completed subtasks that have commitHash values."

3. If found but no completed subtasks have commitHash, output:

   "No completed subtasks with commitHash found. Nothing to analyze."

If prerequisites are met, follow: @context/workflows/ralph/calibration/technical-drift.md

If argument is improve:

Run self-improvement analysis to identify agent inefficiencies from session logs.

Prerequisites check first:

1. Look for subtasks.json in the project root
2. If not found, output a helpful message and exit gracefully:

   "No subtasks.json found. Nothing to analyze for self-improvement.

   To run self-improvement analysis, create a subtasks.json file with completed subtasks that have sessionId values."

3. If found but no completed subtasks have sessionId, output:

   "No completed subtasks with sessionId found. Nothing to analyze."

Check configuration: Read ralph.config.json for the selfImprovement setting which controls behavior:

• "always" (default): Propose-only mode. Creates task files in docs/planning/tasks/ for proposed improvements. Does NOT apply changes directly.
• "auto": Auto-apply mode. Applies changes directly to target files (CLAUDE.md, prompts, skills) without creating task files. Use with caution.
• "never": Skip analysis entirely and exit with a message explaining that self-improvement is disabled.

If prerequisites are met, follow: @context/workflows/ralph/calibration/self-improvement.md

If argument is all:

Run all calibration checks in sequence. Execute each check one after another, following the prerequisite checks and prompts for each:

Step 1: Intention Drift Analysis

• Check prerequisites: subtasks.json exists with completed subtasks having commitHash
• If met, follow: @context/workflows/ralph/calibration/intention-drift.md
• Output intention drift summary

Step 2: Technical Drift Analysis

• Check prerequisites: subtasks.json exists with completed subtasks having commitHash
• If met, follow: @context/workflows/ralph/calibration/technical-drift.md
• Output technical drift summary

Step 3: Self-Improvement Analysis

• Check prerequisites: subtasks.json exists with completed subtasks having sessionId
• If met, follow: @context/workflows/ralph/calibration/self-improvement.md
• Output self-improvement summary

Final Output: Combine all results into a unified summary showing:

• Overall status (all checks passed, issues found, skipped checks)
• Summary of each check that ran
• List of task files created (if any)

If subtasks.json is missing entirely, output:

"No subtasks.json found. Cannot run calibration checks.

To run calibration, create a subtasks.json file with completed subtasks."

If no argument or unknown argument:

Show the usage documentation below.

Usage

/ralph-calibrate <subcommand> [options]

Examples

# Check for intention drift on completed subtasks
/ralph-calibrate intention

# Analyze technical quality patterns
/ralph-calibrate technical

# Analyze session logs for agent inefficiencies
/ralph-calibrate improve

# Run all calibration checks in sequence
/ralph-calibrate all

# Skip approval prompts and create task files automatically
/ralph-calibrate intention --force

# Require approval before creating any task files
/ralph-calibrate all --review

Subcommands

Options

Intention Drift Analysis

Analyzes completed subtasks to detect when code changes have diverged from the intended behavior defined in the planning chain.

What It Checks

• Scope Creep - Code implements more than specified
• Scope Shortfall - Code implements less than acceptance criteria require
• Direction Change - Code solves a different problem than intended
• Missing Link - Code doesn't connect to intended outcome

Output

• Summary to stdout showing drift analysis results
• Task files created in docs/planning/tasks/ for any detected drift

Technical Drift Analysis

Analyzes completed subtasks to detect when code changes have drifted from technical quality standards.

What It Checks

• Missing Tests - Code changes without corresponding test coverage
• Inconsistent Patterns - Code that doesn't follow established codebase patterns
• Missing Error Handling - Critical paths without proper error handling
• Documentation Gaps - Public APIs or complex logic without documentation
• Type Safety Issues - Use of any, type assertions, or missing types
• Security Concerns - Potential security vulnerabilities

Output

• Summary to stdout showing technical quality analysis results
• Task files created in docs/planning/tasks/ for detected technical drift

Self-Improvement Analysis

Analyzes Ralph agent session logs for inefficiencies to propose improvements to prompts, skills, and documentation.

What It Checks

• Tool Misuse - Using Bash for file operations instead of Read/Write/Edit
• Wasted Reads - Files read but never used
• Backtracking - Edits that cancel each other out
• Excessive Iterations - Repeated attempts without changing approach

Configuration

The selfImprovement setting in ralph.config.json controls behavior:

Output

• Summary to stdout showing inefficiency findings
• In propose-only mode ("always"): Task files created in docs/planning/tasks/ for proposed improvements
• In auto-apply mode ("auto"): Changes applied directly to target files (CLAUDE.md, prompts, skills)

CLI Equivalent

This skill provides the same functionality as:

aaa ralph calibrate <subcommand> [options]

References

• Intention drift prompt: @context/workflows/ralph/calibration/intention-drift.md
• Technical drift prompt: @context/workflows/ralph/calibration/technical-drift.md
• Self-improvement prompt: @context/workflows/ralph/calibration/self-improvement.md