Debug Command Storage Skill

Name: debug-command-storage
Rating: 92
Author: hotvect

Purpose

When hotvect operations fail, automatically store the failing command invocation to a file for easy debugging and reproduction.

⚠️ Configuration Protection Policy

CRITICAL: Never modify ~/.hotvect/ configuration files. See CONFIG_PROTECTION_POLICY.md for full policy.

This skill reads ~/.hotvect/config.json for configuration but never modifies it. Work only in user-specified directories.

When to Invoke

Invoke this skill immediately after any command failure:

•hv audit fails with error
•hv train crashes with exception
•hv backtest exits with error code
•hv-ext commands fail
•Java exceptions during hotvect operations
•Any operation that needs to be debugged or replayed

What This Skill Does

•Captures the failing command with all arguments
•Converts to absolute paths for portability
•Replaces algorithm definition JSON paths with algorithm names (when applicable)
•Writes to timestamped file like cmd.tmp.hv.audit.2025-11-17_14-30-45.sh
•Warns user about algorithm name substitution
•Makes file executable for easy replay

Command Naming Convention

Files are named: cmd.tmp.{tool}.{operation}.{timestamp}.sh

Examples:

•cmd.tmp.hv.audit.2025-11-17_14-30-45.sh
•cmd.tmp.hv.train.2025-11-17_15-20-10.sh
•cmd.tmp.java.predict.2025-11-17_16-10-30.sh
•cmd.tmp.hv-ext.show-data-dependency.2025-11-17_17-00-00.sh

Workflow

Step 1: Detect Command Details

From the error context, extract:

•Tool: hv, hv-ext, java, mvn, etc.
•Operation: audit, train, backtest, predict, etc.
•Full command line that was executed
•Working directory where it was run

Step 2: Convert to Absolute Paths

Replace all relative paths with absolute paths:

Before (relative paths):

bash

hv audit \
  --algorithm-jar target/algorithm-77.0.0.jar \
  --algorithm-name my-algo \
  --source-path ../data/test.jsonl \
  --dest-path ./audit.jsonl

After (absolute paths):

bash

hv audit \
  --algorithm-jar /path/to/algorithm/target/algorithm-77.0.0.jar \
  --algorithm-name my-algo \
  --source-path /path/to/data/test.jsonl \
  --dest-path /path/to/workdir/audit.jsonl

Step 3: Replace Algorithm Definition Paths with Names

CRITICAL: If the command used --algorithm-definition /path/to/file.json, replace it with --algorithm-name.

Before (uses temporary JSON file):

bash

hv audit \
  --algorithm-jar /path/to/algorithm.jar \
  --algorithm-definition /tmp/hotvect-12345/modified-algo-def.json \
  --source-path /path/to/data.jsonl

After (uses algorithm name):

bash

hv audit \
  --algorithm-jar /path/to/algorithm.jar \
  --algorithm-name my-algorithm-model \
  --source-path /path/to/data.jsonl

How to get algorithm name:

•Read the algorithm definition JSON file that was used
•Extract the algorithm_name field
•Replace --algorithm-definition /path/to/file.json with --algorithm-name ${extracted_name}

Exception: If you cannot read the algorithm definition file (already deleted), keep the original path and add a comment warning.

Step 4: Create Command File

Generate timestamped filename:

bash

TIMESTAMP=$(date +"%Y-%m-%d_%H-%M-%S")
FILENAME="cmd.tmp.${TOOL}.${OPERATION}.${TIMESTAMP}.sh"

Write file with:

bash

#!/bin/bash
# Generated by Claude Code debug-command-storage skill
# Original command failed at: ${TIMESTAMP}
# Working directory: ${ORIGINAL_PWD}
#
# ⚠️  WARNING: Algorithm definition was converted from JSON file path to algorithm name
# Original: --algorithm-definition /tmp/hotvect-12345/modified-algo-def.json
# Replaced with: --algorithm-name my-algorithm-model
# This assumes the algorithm definition was NOT modified from the bundled version.
# If the original used overrides, this command may behave differently.
#
# To replay this command:
#   bash ${FILENAME}
# Or:
#   chmod +x ${FILENAME}
#   ./${FILENAME}

${ABSOLUTE_PATH_COMMAND}

Step 5: Make Executable and Show User

bash

chmod +x ${FILENAME}
echo "Debug command saved to: ${FILENAME}"
echo ""
echo "To replay:"
echo "  ./${FILENAME}"
echo ""
echo "⚠️  Note: Algorithm definition path was converted to algorithm name."
echo "   If the original command used modified algorithm definition, this replay may differ."

Examples

Example 1: Failed hv audit

Original command (with relative paths):

bash

cd /path/to/workdir
hv audit \
  --algorithm-jar ~/.m2/repository/.../algorithm-77.0.0.jar \
  --algorithm-name my-algorithm-model \
  --source-path ../data/test.jsonl \
  --dest-path audit.jsonl

Saved as cmd.tmp.hv.audit.2025-11-17_14-30-45.sh:

bash

#!/bin/bash
# Generated by Claude Code debug-command-storage skill
# Original command failed at: 2025-11-17_14-30-45
# Working directory: /path/to/workdir

hv audit \
  --algorithm-jar ~/.m2/repository/org/example/relevance/my-algorithm/77.0.0/my-algorithm-77.0.0.jar \
  --algorithm-name my-algorithm-model \
  --source-path /path/to/data/test.jsonl \
  --dest-path /path/to/workdir/audit.jsonl

Example 2: Failed hv train with Algorithm Definition Conversion

Original command (used temporary JSON file):

bash

hv train \
  --algorithm-jar /path/to/algorithm.jar \
  --algorithm-definition /tmp/hotvect-training-12345/modified-algo-def.json \
  --data-base-dir /data \
  --output-base-dir ./output \
  --last-test-time 2025-08-09

Saved as cmd.tmp.hv.train.2025-11-17_15-20-10.sh:

bash

#!/bin/bash
# Generated by Claude Code debug-command-storage skill
# Original command failed at: 2025-11-17_15-20-10
# Working directory: /path/to/workdir
#
# ⚠️  WARNING: Algorithm definition was converted from JSON file path to algorithm name
# Original: --algorithm-definition /tmp/hotvect-training-12345/modified-algo-def.json
# Replaced with: --algorithm-name my-algorithm
# This assumes the algorithm definition was NOT modified from the bundled version.
# If the original used overrides, this command may behave differently.

hv train \
  --algorithm-jar /path/to/algorithm/target/algorithm-77.0.0.jar \
  --algorithm-name my-algorithm \
  --data-base-dir /path/to/data \
  --output-base-dir /path/to/workdir/output \
  --last-test-time 2025-08-09

Example 3: Failed Java Command

Original command:

bash

java -cp hotvect.jar:algorithm.jar \
  com.hotvect.Main \
  --predict \
  --source data/ \
  --dest predictions.jsonl

Saved as cmd.tmp.java.predict.2025-11-17_16-10-30.sh:

bash

#!/bin/bash
# Generated by Claude Code debug-command-storage skill
# Original command failed at: 2025-11-17_16-10-30
# Working directory: /path/to/workdir

java -cp /path/to/hotvect/python/hotvect/hotvectjar/hotvect-offline-util-10.0.0-jar-with-dependencies.jar:~/.m2/repository/.../algorithm-77.0.0.jar \
  com.hotvect.Main \
  --predict \
  --source /path/to/data/ \
  --dest /path/to/workdir/predictions.jsonl

Important Notes

Algorithm Name vs Definition Path

Why we convert to algorithm name:

•Portability: Temporary JSON files get deleted, making commands unreplayable
•Simplicity: Algorithm name is more user-friendly
•Common case: Most operations don't modify the bundled definition

When this conversion is safe:

•Original command used algorithm name (no conversion needed)
•Original command used algorithm definition path, but didn't modify it from bundled version
•No algorithm overrides were applied

When this conversion may cause differences:

•Original command used modified algorithm definition (with overrides applied)
•Training operations that applied override files
•Backtest operations with custom algorithm configurations

Always warn user about this conversion so they understand the replay might differ.

Absolute Paths Are Critical

Using absolute paths ensures:

•Command can be replayed from any directory
•No confusion about what files were used
•Easy to share with others for debugging

File Location

Save files in the current working directory where the command failed. This makes them easy to find and keeps them with related debugging artifacts.

Error Handling

If you cannot determine certain information:

•Algorithm name unknown: Keep original --algorithm-definition path and warn it may not exist
•Relative path can't be resolved: Use best guess or keep relative with warning
•Working directory unknown: Use current directory

Always prioritize saving something useful over failing to save anything.

User Communication

After saving the command, tell the user:

•Where the file is: Full path to the .sh file
•How to replay it: ./cmd.tmp.hv.audit.2025-11-17_14-30-45.sh
•Warning about algorithm definition (if converted)
•What to check: Suggest what might have caused the failure

Example message:

code

Debug command saved to: /path/to/workdir/cmd.tmp.hv.audit.2025-11-17_14-30-45.sh

To replay this command:
  cd /path/to/workdir
  ./cmd.tmp.hv.audit.2025-11-17_14-30-45.sh

⚠️  Note: Algorithm definition path was converted to algorithm name.
   If the original used modified definition, replay may behave differently.

The failure may be due to:
- Missing test data at the specified path
- Algorithm JAR version mismatch
- Java heap space (try increasing with --extra-jvm-args)

Debug Command Storage Skill

Purpose

⚠️ Configuration Protection Policy

When to Invoke

What This Skill Does

Command Naming Convention

Workflow

Step 1: Detect Command Details

Step 2: Convert to Absolute Paths

Step 3: Replace Algorithm Definition Paths with Names

Step 4: Create Command File

Step 5: Make Executable and Show User

Examples

Example 1: Failed hv audit

Example 2: Failed hv train with Algorithm Definition Conversion

Example 3: Failed Java Command

Important Notes

Algorithm Name vs Definition Path

Absolute Paths Are Critical

File Location

Error Handling

User Communication

Related Documentation