Skill: environment-doctor

Purpose

Ensure a consistent and healthy development environment across all Ralph iterations. This skill prevents the agent from wasting time debugging issues caused by environment drift.

When to Use

•At the start of every Ralph iteration as a pre-flight check.
•When tests or builds fail with errors related to missing dependencies or version mismatches.

How It Works

Step 1: Create Environment Lock File (One-Time Setup)

At the start of a new project, create a .ralph/environment.lock file:

bash

# For Node.js
echo "{
  \"node\": \"$(node -v)\",
  \"npm\": \"$(npm -v)\",
  \"dependencies_hash\": \"$(md5sum package-lock.json | cut -d' ' -f1)\"
}" > .ralph/environment.lock

# For Python
echo "{
  \"python\": \"$(python3 --version | cut -d' ' -f2)\",
  \"pip\": \"$(pip3 --version | cut -d' ' -f2)\",
  \"dependencies_hash\": \"$(md5sum requirements.txt | cut -d' ' -f1)\"
}" > .ralph/environment.lock

Step 2: Run Pre-Flight Check

At the start of each iteration, run the following checks:

bash

# Check Node.js version
EXPECTED_NODE=$(jq -r '.node' .ralph/environment.lock)
ACTUAL_NODE=$(node -v)
if [ "$EXPECTED_NODE" != "$ACTUAL_NODE" ]; then
  echo "WARNING: Node.js version mismatch. Expected $EXPECTED_NODE, got $ACTUAL_NODE."
fi

# Check dependencies hash
EXPECTED_HASH=$(jq -r '.dependencies_hash' .ralph/environment.lock)
ACTUAL_HASH=$(md5sum package-lock.json | cut -d' ' -f1)
if [ "$EXPECTED_HASH" != "$ACTUAL_HASH" ]; then
  echo "WARNING: Dependencies have changed. Running npm install..."
  npm install
fi

Step 3: Auto-Heal Common Issues

Issue	Auto-Heal Action
Dependencies changed	Run `npm install` or `pip install -r requirements.txt`
Missing build artifacts	Run `npm run build` or equivalent
Stale cache	Clear cache directories (e.g., `.next`, `__pycache__`)

Step 4: Escalate Unfixable Issues

If the pre-flight check detects an issue it cannot fix (e.g., wrong Node.js version), it should:

•Log the issue to progress.txt.
•Mark the current story as blocked-environment.
•Add a notes field explaining the issue and required human intervention.

Configuration

Add the following to your CLAUDE.md:

markdown

## Environment Doctor

- **Lock File**: `.ralph/environment.lock`
- **Auto-Heal**: Enabled
- **Checks**: Node version, dependency hash, build artifacts