Session Guidance Skill

Configure Ralph loop session guidance through AskUserQuestion flows. Loads constraint scan results, presents dynamic options based on severity, and writes guidance to config.

When to Use

• Invoked by /ralph:start Step 1.6 via Skill tool
• User asks to reconfigure Ralph guidance
• User mentions "forbidden items" or "encouraged items"

Prerequisites

• Step 1.4 constraint scan completed (.claude/ralph-constraint-scan.jsonl exists)
• Step 1.5 preset confirmation completed

Workflow Overview

1.6.1: Check for Previous Guidance
         ↓
1.6.2: Binary Keep/Reconfigure (if guidance exists)
         ↓
1.6.2.5: Load Constraint Scan Results (NDJSON)
         ↓
1.6.3: Forbidden Items (multiSelect, DYNAMIC from constraints)
         ↓
1.6.4: Custom Forbidden (follow-up)
         ↓
1.6.5: Encouraged Items (multiSelect, closed list)
         ↓
1.6.6: Custom Encouraged (follow-up)
         ↓
1.6.7: Update Config (with validation + learned behavior)

Step 1.6.1: Check for Previous Guidance

Check if guidance exists in the config file:

/usr/bin/env bash << 'CHECK_GUIDANCE_SCRIPT'
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
GUIDANCE_EXISTS="false"
if [[ -f "$PROJECT_DIR/.claude/ralph-config.json" ]]; then
    GUIDANCE_EXISTS=$(jq -r 'if .guidance then "true" else "false" end' "$PROJECT_DIR/.claude/ralph-config.json" 2>/dev/null || echo "false")
fi
echo "GUIDANCE_EXISTS=$GUIDANCE_EXISTS"
CHECK_GUIDANCE_SCRIPT

Step 1.6.2: Binary Keep/Reconfigure (Conditional)

If GUIDANCE_EXISTS == "true":

Use AskUserQuestion:

• question: "Previous session had custom guidance. Keep it or reconfigure?" header: "Guidance" options:

  • label: "Keep existing guidance (Recommended)" description: "Use stored forbidden/encouraged lists from last session"
  • label: "Reconfigure guidance" description: "Set new forbidden/encouraged lists" multiSelect: false

• If "Keep existing" → STOP skill execution (guidance already in config, return to start.md Step 2)

• If "Reconfigure" → Continue to Step 1.6.2.5

If GUIDANCE_EXISTS == "false" (first run):

Proceed directly to Step 1.6.2.5. No user prompt needed.

Step 1.6.2.5: Load Constraint Scan Results (NDJSON)

Purpose: Load constraint scan results in NDJSON format, filtering out previously acknowledged constraints.

Learned behavior: Constraints the user previously selected as "forbidden" are stored in .claude/ralph-acknowledged-constraints.jsonl and filtered from future displays.

/usr/bin/env bash << 'LOAD_SCAN_SCRIPT'
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
SCAN_FILE="$PROJECT_DIR/.claude/ralph-constraint-scan.jsonl"
ACK_FILE="$PROJECT_DIR/.claude/ralph-acknowledged-constraints.jsonl"

if [[ -f "$SCAN_FILE" ]]; then
    # Load acknowledged constraint IDs (if file exists)
    ACKNOWLEDGED_IDS=""
    if [[ -f "$ACK_FILE" ]]; then
        ACKNOWLEDGED_IDS=$(jq -r 'select(._type == "constraint") | .id' "$ACK_FILE" 2>/dev/null | tr '\n' '|' | sed 's/|$//')
        ACK_COUNT=$(grep -c '"_type":"constraint"' "$ACK_FILE" 2>/dev/null || echo "0")
        echo "=== ACKNOWLEDGED CONSTRAINTS ==="
        echo "Previously acknowledged: $ACK_COUNT constraints (filtered from display)"
        echo ""
    fi

    # NDJSON format: each line is a JSON object with _type field
    # Filter out acknowledged constraints and count by severity
    if [[ -n "$ACKNOWLEDGED_IDS" ]]; then
        FILTERED=$(grep '"_type":"constraint"' "$SCAN_FILE" 2>/dev/null | \
            jq -c --arg ack_pattern "$ACKNOWLEDGED_IDS" 'select(.id | test($ack_pattern) | not)' 2>/dev/null)
    else
        FILTERED=$(grep '"_type":"constraint"' "$SCAN_FILE" 2>/dev/null)
    fi

    # Count by severity (from filtered NDJSON lines)
    CRITICAL_COUNT=$(echo "$FILTERED" | jq -s '[.[] | select(.severity == "critical")] | length' 2>/dev/null || echo "0")
    HIGH_COUNT=$(echo "$FILTERED" | jq -s '[.[] | select(.severity == "high")] | length' 2>/dev/null || echo "0")
    MEDIUM_COUNT=$(echo "$FILTERED" | jq -s '[.[] | select(.severity == "medium")] | length' 2>/dev/null || echo "0")
    LOW_COUNT=$(echo "$FILTERED" | jq -s '[.[] | select(.severity == "low")] | length' 2>/dev/null || echo "0")
    TOTAL_COUNT=$((CRITICAL_COUNT + HIGH_COUNT + MEDIUM_COUNT + LOW_COUNT))
    BUSYWORK_COUNT=$(grep -c '"_type":"busywork"' "$SCAN_FILE" 2>/dev/null || echo "0")

    echo "=== CONSTRAINT SCAN SUMMARY ==="
    echo "SEVERITY_COUNTS: critical=$CRITICAL_COUNT high=$HIGH_COUNT medium=$MEDIUM_COUNT low=$LOW_COUNT total=$TOTAL_COUNT"
    echo "BUSYWORK_COUNT: $BUSYWORK_COUNT"
    echo ""
    echo "=== CONSTRAINTS (NDJSON) ==="
    echo "$FILTERED"
    echo ""
    echo "=== BUSYWORK CATEGORIES (NDJSON) ==="
    grep '"_type":"busywork"' "$SCAN_FILE" 2>/dev/null
    echo ""
    echo "=== END SCAN RESULTS ==="
else
    echo "=== CONSTRAINT SCAN SUMMARY ==="
    echo "SEVERITY_COUNTS: critical=0 high=0 medium=0 low=0 total=0"
    echo "BUSYWORK_COUNT: 0"
    echo "=== NO SCAN FILE FOUND ==="
fi
LOAD_SCAN_SCRIPT

Claude MUST parse this output:

1. Extract severity counts from SEVERITY_COUNTS: line for question text
2. Parse NDJSON constraints between === CONSTRAINTS (NDJSON) === and === BUSYWORK CATEGORIES ===
3. Parse NDJSON busywork between === BUSYWORK CATEGORIES (NDJSON) === and === END SCAN RESULTS ===
4. Build dynamic AUQ options with constraint-derived items first, then static fallbacks

NDJSON constraint format (one per line):

{"id":"hardcoded-001","severity":"high","category":"hardcoded_path","description":"Hardcoded path: /Users/terryli/...","file":"pyproject.toml","line":15,"recommendation":"Use environment variable"}

Step 1.6.3: Forbidden Items (multiSelect, DYNAMIC)

MANDATORY: Build options dynamically from Step 1.6.2.5 output

AUQ Limit: Maximum 4 options total. Priority order:

1. CRITICAL severity constraints (up to 2)
2. HIGH severity constraints (up to 2)
3. If <4 constraint options, fill with static categories

Algorithm - Claude MUST execute this logic:

Step 1: Parse severity counts from SEVERITY_COUNTS line
  - Extract: critical=N, high=M, total=T

Step 2: Build constraint options (max 4, severity priority)
  options = []

  # First: CRITICAL constraints (max 2)
  for each NDJSON line where severity == "critical":
    if len(options) >= 2: break
    options.append({
      label: description[:55] + "..." if len > 55 else description,
      description: "(CRITICAL) " + file + ":" + line + " - " + recommendation[:40]
    })

  # Second: HIGH constraints (max 2 more)
  for each NDJSON line where severity == "high":
    if len(options) >= 4: break
    options.append({
      label: description[:55] + "..." if len > 55 else description,
      description: "(HIGH) " + file + ":" + line + " - " + recommendation[:40]
    })

  # Third: Fill remaining with static categories
  static_categories = ["Documentation updates", "Dependency upgrades", "Refactoring", "CI/CD modifications"]
  while len(options) < 4 and static_categories:
    options.append(static_categories.pop(0))

Step 3: Build question text
  if critical > 0 or high > 0:
    question = "What should Ralph avoid? ({critical} critical, {high} high detected)"
  else:
    question = "What should Ralph avoid? (no high-severity constraints)"

Example transformation:

NDJSON input:

{"severity":"critical","description":"Hardcoded API key in config.py","file":"config.py","line":42,"recommendation":"Move to env var"}
{"severity":"high","description":"Circular import: core ↔ utils","file":"core.py","line":1,"recommendation":"Extract interface"}

Becomes AUQ options:

options:
  - label: "Hardcoded API key in config.py"
    description: "(CRITICAL) config.py:42 - Move to env var"
  - label: "Circular import: core ↔ utils"
    description: "(HIGH) core.py:1 - Extract interface"
  - label: "Documentation updates"
    description: "README, CHANGELOG, docstrings, comments"
  - label: "Dependency upgrades"
    description: "Version bumps, renovate PRs, package updates"

Use AskUserQuestion with the dynamically built options above.

Static fallback categories (used when no constraints or to fill remaining slots):

• "Documentation updates" - "README, CHANGELOG, docstrings, comments"
• "Dependency upgrades" - "Version bumps, renovate PRs, package updates"
• "Refactoring" - "Code restructuring without behavior change"
• "CI/CD modifications" - "Workflow files, GitHub Actions, pipelines"

If total=0: Show only 4 static categories with question "What should Ralph avoid? (no constraints detected)"

Step 1.6.4: Custom Forbidden (Follow-up)

After multiSelect, ask for custom additions:

Use AskUserQuestion:

• question: "Add custom forbidden items? (comma-separated)" header: "Custom" multiSelect: false options:
  • label: "Enter custom items" description: "Type additional forbidden phrases, e.g., 'database migrations, API changes'"
  • label: "Skip custom items" description: "Use only selected categories above"

If "Enter custom items" selected → Parse user's "Other" input, split by comma, trim whitespace.

Step 1.6.5: Encouraged Items (multiSelect, closed list)

Use AskUserQuestion:

• question: "What should Ralph prioritize? (Select all that apply)" header: "Encouraged" multiSelect: true options:
  • label: "ROADMAP P0 items" description: "Highest priority tasks from project roadmap"
  • label: "Performance improvements" description: "Speed, memory, efficiency optimizations"
  • label: "Bug fixes" description: "Fix known issues and regressions"
  • label: "Research experiments" description: "Try new approaches (Alpha Forge /research)"

Step 1.6.6: Custom Encouraged (Follow-up)

Same pattern as 1.6.4:

Use AskUserQuestion:

• question: "Add custom encouraged items? (comma-separated)" header: "Custom" multiSelect: false options:
  • label: "Enter custom items" description: "Type additional encouraged phrases, e.g., 'Sharpe ratio, feature engineering'"
  • label: "Skip custom items" description: "Use only selected categories above"

Step 1.6.7: Update Config (with Validation + Learned Behavior)

IMPORTANT: After collecting responses from Steps 1.6.3-1.6.6, you MUST:

1. Write guidance to config WITH validation

2. Append constraint-derived selections to .jsonl for learned filtering

3. Collect responses from the AUQ steps above:

   • FORBIDDEN_ITEMS: Selected labels from 1.6.3 + custom items from 1.6.4 (if any)
   • ENCOURAGED_ITEMS: Selected labels from 1.6.5 + custom items from 1.6.6 (if any)
   • SELECTED_CONSTRAINT_IDS: IDs of constraint-derived options user selected (from NDJSON parsing)

4. Write to config with post-write validation using the Bash tool (substitute actual values):

/usr/bin/env bash << 'GUIDANCE_WRITE_SCRIPT'
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
CONFIG_FILE="$PROJECT_DIR/.claude/ralph-config.json"
SCAN_FILE="$PROJECT_DIR/.claude/ralph-constraint-scan.jsonl"
ACK_FILE="$PROJECT_DIR/.claude/ralph-acknowledged-constraints.jsonl"
BACKUP_FILE="${CONFIG_FILE}.backup"

# Substitute these with actual AUQ responses:
FORBIDDEN_JSON='["Documentation updates", "Dependency upgrades"]'  # From 1.6.3 + 1.6.4
ENCOURAGED_JSON='["ROADMAP P0 items", "Research experiments"]'     # From 1.6.5 + 1.6.6

# Substitute with constraint IDs user selected (from NDJSON constraint options)
SELECTED_CONSTRAINT_IDS="hardcoded-001 hardcoded-002"  # From 1.6.3 constraint-derived selections

# Generate timestamp
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# Load constraint scan data (if exists) for persistence
CONSTRAINT_SCAN_JSON='null'
if [[ -f "$SCAN_FILE" ]]; then
    METADATA=$(grep '"_type":"metadata"' "$SCAN_FILE" 2>/dev/null | head -1)
    CONSTRAINTS=$(grep '"_type":"constraint"' "$SCAN_FILE" 2>/dev/null | jq -s '.' 2>/dev/null || echo '[]')
    BUSYWORK=$(grep '"_type":"busywork"' "$SCAN_FILE" 2>/dev/null | jq -s '.' 2>/dev/null || echo '[]')

    CONSTRAINT_SCAN_JSON=$(jq -n \
        --argjson metadata "$METADATA" \
        --argjson constraints "$CONSTRAINTS" \
        --argjson busywork "$BUSYWORK" \
        '{
            scan_timestamp: $metadata.scan_timestamp,
            project_dir: $metadata.project_dir,
            worktree_type: $metadata.worktree_type,
            constraints: $constraints,
            builtin_busywork: $busywork
        }' 2>/dev/null || echo 'null')
fi

# Create backup before write
mkdir -p "$PROJECT_DIR/.claude"
if [[ -f "$CONFIG_FILE" ]]; then
    cp "$CONFIG_FILE" "$BACKUP_FILE"
fi

# Write config
if [[ -f "$CONFIG_FILE" ]]; then
    jq --argjson forbidden "$FORBIDDEN_JSON" \
       --argjson encouraged "$ENCOURAGED_JSON" \
       --arg timestamp "$TIMESTAMP" \
       --argjson constraint_scan "$CONSTRAINT_SCAN_JSON" \
       '.guidance = {forbidden: $forbidden, encouraged: $encouraged, timestamp: $timestamp} | .constraint_scan = $constraint_scan' \
       "$CONFIG_FILE" > "${CONFIG_FILE}.tmp" && mv "${CONFIG_FILE}.tmp" "$CONFIG_FILE"
else
    jq -n --argjson forbidden "$FORBIDDEN_JSON" \
          --argjson encouraged "$ENCOURAGED_JSON" \
          --arg timestamp "$TIMESTAMP" \
          --argjson constraint_scan "$CONSTRAINT_SCAN_JSON" \
          '{version: "3.0.0", guidance: {forbidden: $forbidden, encouraged: $encouraged, timestamp: $timestamp}, constraint_scan: $constraint_scan}' \
          > "$CONFIG_FILE"
fi

# === LEARNED BEHAVIOR: Append to .jsonl ===
if [[ -n "$SELECTED_CONSTRAINT_IDS" && -f "$SCAN_FILE" ]]; then
    for CONSTRAINT_ID in $SELECTED_CONSTRAINT_IDS; do
        if [[ -f "$ACK_FILE" ]] && grep -q "\"id\":\"$CONSTRAINT_ID\"" "$ACK_FILE" 2>/dev/null; then
            continue
        fi
        CONSTRAINT_DATA=$(grep "\"id\":\"$CONSTRAINT_ID\"" "$SCAN_FILE" 2>/dev/null | head -1 | \
            jq -c --arg ts "$TIMESTAMP" '. + {acknowledged_at: $ts}' 2>/dev/null)
        if [[ -n "$CONSTRAINT_DATA" ]]; then
            echo "$CONSTRAINT_DATA" >> "$ACK_FILE"
        fi
    done
    NEW_ACK_COUNT=$(echo "$SELECTED_CONSTRAINT_IDS" | wc -w | tr -d ' ')
    echo "=== LEARNED BEHAVIOR ==="
    echo "Appended $NEW_ACK_COUNT constraint(s) to $ACK_FILE"
fi

# === POST-WRITE VALIDATION ===
validate_config() {
    local file="$1"
    [[ -f "$file" && -r "$file" ]] || return 1
    jq empty "$file" >/dev/null 2>&1 || return 2
    jq -e '.guidance.forbidden and .guidance.encouraged and .guidance.timestamp' "$file" >/dev/null 2>&1 || return 3
    jq -e '.guidance.forbidden | type == "array"' "$file" >/dev/null 2>&1 || return 4
    jq -e '.guidance.encouraged | type == "array"' "$file" >/dev/null 2>&1 || return 5
    return 0
}

if validate_config "$CONFIG_FILE"; then
    echo "✓ Guidance saved to $CONFIG_FILE"
    echo ""
    echo "=== VALIDATION PASSED ==="
    jq '{guidance: .guidance}' "$CONFIG_FILE"
    rm -f "$BACKUP_FILE"
else
    VALIDATION_ERROR=$?
    echo "✗ VALIDATION FAILED (error code: $VALIDATION_ERROR)"
    echo "=== ROLLING BACK ==="
    if [[ -f "$BACKUP_FILE" ]]; then
        mv "$BACKUP_FILE" "$CONFIG_FILE"
        echo "Restored previous config from backup"
    else
        rm -f "$CONFIG_FILE"
        echo "Removed invalid config"
    fi
    exit 1
fi
GUIDANCE_WRITE_SCRIPT

Key substitutions Claude MUST make:

• FORBIDDEN_JSON: Array of selected forbidden labels
• ENCOURAGED_JSON: Array of selected encouraged labels
• SELECTED_CONSTRAINT_IDS: Space-separated list of constraint IDs from NDJSON options user selected

Output

After completing all steps, the skill returns control to /ralph:start Step 2 (Execution).

The config file .claude/ralph-config.json will contain:

{
  "version": "3.0.0",
  "guidance": {
    "forbidden": ["Documentation updates", "..."],
    "encouraged": ["ROADMAP P0 items", "..."],
    "timestamp": "2026-01-01T00:00:00Z"
  },
  "constraint_scan": { ... }
}