ralph-calibrate

name	ralph-calibrate
description	Run Ralph calibration checks to analyze intention drift, technical quality, and self-improvement opportunities. Use when user asks to "ralph calibrate", "check drift", "analyze sessions", or needs to verify work alignment.

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

Subcommand	Description
intention	Analyze intention drift between planning and implementation
technical	Analyze technical quality patterns (tests, types, error handling)
improve	Analyze session logs for agent inefficiencies
all	Run all calibration checks sequentially

Options

Option	Description
--force	Skip approval prompts, create task files automatically
--review	Require approval before creating task files

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:

Setting	Mode	Behavior
"always"	Propose-only	Creates task files for review, does NOT apply changes
"auto"	Auto-apply	Applies changes directly to target files
"never"	Disabled	Skips analysis entirely

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