ralphex-update - Smart Prompt Merging

SCOPE: Compare current embedded defaults with user's installed config, and intelligently merge updates into customized files. Preserves user intent while incorporating structural changes.

Step 0: Verify CLI Installation

which ralphex

If not found, guide installation:

• macOS (Homebrew): brew install umputun/apps/ralphex
• Any platform with Go: go install github.com/umputun/ralphex/cmd/ralphex@latest

Do not proceed until which ralphex succeeds.

Step 1: Extract Current Defaults

Create temp directory and dump embedded defaults:

DUMP_DIR=$(mktemp -d /tmp/ralphex-defaults-XXXX)
ralphex --dump-defaults "$DUMP_DIR"
echo "$DUMP_DIR"

Save the dump directory path for later use.

Step 2: Determine Config Directory

Resolve the user's config directory:

# check environment variable first
echo "${RALPHEX_CONFIG_DIR:-}"

If RALPHEX_CONFIG_DIR is empty, use default:

• macOS/Linux: ~/.config/ralphex/

Verify the directory exists:

ls -la <config-dir>/

If it doesn't exist, inform user that ralphex hasn't been configured yet and there's nothing to update.

How ralphex Config Files Work

ralphex installs config, prompt, and agent files with all content commented out (every line prefixed with # ). At runtime, stripComments() removes these lines, finds nothing, and falls back to embedded defaults compiled into the binary. These all-commented files are functionally identical to missing files — they are do-nothing placeholders.

When ralphex is updated, new embedded defaults take effect automatically for every file that hasn't been customized. No file changes are needed.

A file is customized only if it contains at least one uncommented, non-empty line that was intentionally modified by the user. The --dump-defaults command produces the raw (uncommented) embedded content for comparison.

Step 3: Compare Files

For each file in the defaults dump (config, prompts/*.txt, agents/*.txt), compare with the corresponding file in the user's config directory.

Algorithm to detect customized files: a file is customized if it contains at least one non-empty line that does NOT start with #. Files that are missing, empty, or contain only comment lines (# ...) and whitespace are do-nothing defaults.

Classify each file into one of these categories:

Skip (do-nothing default)

• File is missing in user's config, OR
• File is empty, OR
• File contains only comments and whitespace (every non-empty line starts with #)
• Action: no action needed — embedded defaults handle it automatically

Note: files that exist only in the dump directory (no corresponding user file) are also do-nothing — do NOT offer to install them. Files that exist only in the user's config directory (no corresponding dump file) are user-created custom files — ignore them entirely.

Skip (unchanged)

• File has uncommented content that matches the raw dump default
• Action: no action needed — user's file already matches current defaults

How to compare: strip all #-prefixed lines from BOTH the user's file and the dump file, then compare the remaining non-comment content. This handles the config file where the dump has descriptive comment lines mixed with value lines — only the actual values matter for comparison.

Smart merge needed

• File has uncommented content that differs from the raw dump default (after stripping #-prefixed lines from both sides)
• Action: needs Claude to semantically analyze and propose merge

Step 4: Present Summary

Show the user a summary with two groups:

ralphex config update summary:

No changes needed (N files):
  prompts/task.txt, prompts/review_first.txt, agents/quality.txt, prompts/codex.txt, ...

Smart merge needed (N files):
  prompts/review_second.txt, agents/implementation.txt

If nothing needs merging, report "all config files are up to date — no changes needed" and skip to cleanup.

Otherwise, use AskUserQuestion to confirm proceeding:

• header: "Proceed"
• question: "Review smart merges? Each customized file will be reviewed one by one."
• options:
  • label: "Yes, proceed" description: "Review and merge customized files one at a time"
  • label: "Skip, just show details" description: "Show what changed without modifying anything"

If user selects "Skip, just show details": for each file needing smart merge, show the diff between the user's file and the new default, then skip to Step 6 (Cleanup) without modifying any files.

Step 5: Process Smart Merges

For each customized file that needs merging:

1. Read both versions - the new default and the user's current version

2. Analyze the differences semantically:

   • What did the user customize? (added content, changed wording, different instructions)
   • What changed in the new default? (structural changes, new template variables, new sections, removed sections)

3. Propose a merged version that:

   • Preserves user additions not present in defaults
   • Applies structural/pattern changes from new defaults
   • Updates template variable references (e.g., new {{VARIABLE}} usage)
   • Preserves user's tone and style choices
   • Flags direct conflicts where both changed the same thing

4. Show the user:

   • Brief summary of what changed in defaults
   • Brief summary of what user customized
   • The proposed merged version

5. Use AskUserQuestion for each file:

   • header: "Merge"
   • question: "How to handle ?"
   • options:
     • label: "Accept merge" description: "Use the proposed merged version"
     • label: "Keep mine" description: "Keep your current version unchanged"
     • label: "Use new default" description: "Replace with new default (discard customizations)"

6. Apply the user's choice

Step 6: Cleanup

Remove the temp directory:

rm -rf <dump-dir>

Report final summary:

Update complete:
  Skipped: N files (no changes needed)
  Smart-merged: N files (M accepted, K kept)

Merge Principles

When proposing smart merges, follow these rules:

• Preserve user additions: content the user added that doesn't exist in defaults should be kept
• Apply structural changes: if defaults restructured prompts (e.g., changed from sequential to parallel agents), apply the new structure while keeping user's custom content
• Update template variables: if new {{VARIABLE}} references were added to defaults, include them in the merge
• Preserve user tone/style: if user rewrote instructions in a different style, keep their style while incorporating new functionality
• Flag conflicts clearly: if both user and defaults changed the same section differently, present both versions and let the user choose
• Don't lose information: when in doubt, keep both versions with clear markers

Constraints

• This command is ONLY for updating ralphex configuration files
• Do NOT modify any project source code
• Do NOT run ralphex execution or review
• Do NOT touch files outside the config directory
• Always clean up the temp directory when done