Menú
Guide for debugging X-Fidelity analysis issues. Use when troubleshooting analysis failures, rule evaluation problems, VSCode extension issues, or unexpected results.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | xfi-debug-analysis |
| description | Guide for debugging X-Fidelity analysis issues. Use when troubleshooting analysis failures, rule evaluation problems, VSCode extension issues, or unexpected results. |
This skill guides you through troubleshooting X-Fidelity analysis issues.
Debugging Checklist:
- [ ] Check Output panel for errors
- [ ] Verify archetype detection
- [ ] Review file inclusion/exclusion patterns
- [ ] Test rule evaluation
- [ ] Compare CLI vs VSCode output
- [ ] Check plugin loading status
CLI:
xfi --debug
VSCode Extension:
| Level | When to Use |
|---|---|
info | Normal operation (default) |
debug | Detailed execution flow |
trace | Full diagnostic output |
Symptoms: No issues found, analysis seems to skip
Diagnostic Steps:
# Verify files match inclusion patterns
xfi --debug 2>&1 | grep -E "(whitelist|blacklist|skip)"
# Check archetype configuration
cat .xfi-config.json
Common Causes:
Solution:
Check whitelistPatterns and blacklistPatterns in archetype config:
{
"whitelistPatterns": [".*\\.(ts|tsx|js|jsx)$"],
"blacklistPatterns": [".*\\/node_modules\\/.*"]
}
Symptoms: Expected issue not appearing
Diagnostic Steps:
# Check archetype includes the rule
cat packages/x-fidelity-democonfig/src/{archetype}.json | grep "ruleName"
xfi --debug 2>&1 | grep -E "fact|operator"
all (AND) or any (OR)?REPO_GLOBAL_CHECK condition present?Solution: Review rule JSON structure - see xfi-create-rule skill
Symptoms: Issue appearing on files that should pass
Diagnostic Steps:
# View what the fact is seeing
xfi --debug 2>&1 | grep -A5 "factName"
Solution:
Symptoms: Extension shows no issues but CLI finds them
Diagnostic Steps:
Check Output panel:
Verify workspace:
Run extension test:
Compare with CLI:
cd /path/to/workspace
xfi --archetype node-fullstack
Common Causes:
Solution:
Symptoms: CLI and VSCode show different issues
Diagnostic Steps:
# Run consistency test
yarn test:consistency
# Check both outputs
xfi --mode cli # Human-readable
xfi --mode vscode # Clean JSON output
Common Causes:
Solution:
# Ensure build is current
yarn build
# Verify same configuration
cat .xfi-config.json
Symptoms: "Plugin not found" or "Failed to load"
Diagnostic Steps:
xfi --debug 2>&1 | grep -E "(plugin|load|register)"
Common Causes:
Solution:
packages/x-fidelity-plugins/src/index.tsyarn workspace @x-fidelity/plugins testSymptoms: "Tree-sitter" errors, AST facts returning empty
Diagnostic Steps:
Check WASM status in VSCode:
Verify WASM files exist:
ls packages/x-fidelity-vscode/dist/*.wasm
xfi --debug 2>&1 | grep -E "(tree-sitter|wasm|parse)"
Solution:
# Rebuild with WASM copy
yarn workspace x-fidelity-vscode build
# Verify WASM files
ls -la dist/*.wasm
Symptoms: Analysis taking too long or timing out
Diagnostic Steps:
# Check file count
find . -name "*.ts" -o -name "*.tsx" | wc -l
# Run with timing
time xfi --debug
Common Causes:
Solution:
packages/x-fidelity-vscode in VSCodeUse Control Center > Development Tools > Debug Info to copy:
| Output Channel | Content |
|---|---|
| X-Fidelity Debug | Extension lifecycle, errors |
| X-Fidelity Analysis | Analysis execution, file processing |
File logs (if enabled with --enable-file-logging):
.xfiResults/x-fidelity.log# Full debug output
xfi --debug 2>&1 | tee debug.log
# Just errors
xfi 2>&1 | grep -i error
# Rule evaluation
xfi --debug 2>&1 | grep -E "(rule|condition|event)"
# File processing
xfi --debug 2>&1 | grep -E "(file|scan|process)"
# Plugin activity
xfi --debug 2>&1 | grep -E "(plugin|fact|operator)"
| Purpose | Location |
|---|---|
| Debug output | Output panel > "X-Fidelity Debug" |
| Analysis logs | Output panel > "X-Fidelity Analysis" |
| File logs | .xfiResults/x-fidelity.log |
| Extension code | packages/x-fidelity-vscode/src/ |
| CLI code | packages/x-fidelity-cli/src/ |
| Core engine | packages/x-fidelity-core/src/core/engine/ |
Multi-purpose utility for CRUX compression workflows. Provides token estimation and checksum calculation. Use when estimating tokens for compression, comparing file sizes, or getting checksums for sourceChecksum tracking.
Guide for creating engineering plans through a structured workflow. Use when planning new features, coordinating multi-agent work, or breaking down complex initiatives.
Guide for executing engineering plans through coordinated subagent work. Use when executing existing plans from knowledge/plans/ directory.
Guide for creating a new package in the X-Fidelity monorepo. Use when adding new packages, setting up monorepo structure, or configuring workspace dependencies.
Guide for ensuring CLI and VSCode extension produce identical analysis results. Use when verifying CLI-Extension parity, debugging output differences, or setting up consistency checks.
Guide for creating a new X-Fidelity archetype configuration. Use when defining project templates, configuring rule sets, or setting up dependency requirements.