The agent and skill definitions had drifted badly from the current
codebase and tooling, repeating the same class of bug as the benchmark
tool (references to nonexistent scripts and invented flags):

- Replace the removed `python3 test.py` with the real integration
  command (`python3 -m pytest tests/integration/ -n 4 --dist=load
  -m "not setpriv"`) across agents and skills.
- Fix `feature-scout`'s fabricated CLI flag list (--host, --server-mode,
  --use-* etc.) using the authoritative src/client/usage.c flags.
- Fix `perf-analyst` benchmark flags (-m -c -> -j -z) and point at
  benchmark/bench.py instead of stale numbers.
- Correct `code-explainer` (no getopt_long; --sendfile not -f) and
  version drift in the release skill (1.1.0 -> 2.20.0).
- Replace GitHub/`gh` workflows with Gitea/`tea` (PRs target dev; issues
  via tea; branch strategy updated in all agents).
- Use the built-in `-DSANITIZER=address|thread` CMake option instead of
  hand-rolled -fsanitize flags.
- Add `-p 8080 --allow-unauthenticated` to plain-TCP server examples.
- Merge the redundant security-screener into security-auditor; drop the
  duplicate (16 agents remain).

Repo hygiene: gitignore `root/` and `test_partial_install_tmp/`, remove
the empty leftover trees, delete the tracked scratch scripts tmux.sh and
to_one_file.py, and note the compile_commands.json symlink in README.

2026-09-13 10:34:59 +02:00

3.3 KiB

Raw Blame History

name, description

name	description
debug-workflow	Debugs crashes, memory errors, hangs, and logic bugs in FastSync using structured methodology. Use when the user says "debug X", "fix crash", "investigate failure", "there's a bug", or needs help diagnosing issues.

Debug Workflow Skill

Structured debugging for FastSync: reproduce → isolate → diagnose → fix → verify. This skill CAN edit files, build, and run tests.

Workflow

Step 1: Understand the Problem

Ask or gather:

What's the symptom? (crash, hang, wrong output, valgrind error)
What command triggers it?
Is it deterministic or intermittent?
What's the environment? (OS, compiler, network conditions)

Step 2: Reproduce

Build with debug info:

rm -rf build
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)

Try to reproduce the issue with the exact command the user provides.

Step 3: Isolate with Sanitizers

Memory errors (first priority):

rm -rf build-asan
cmake -B build-asan -S . -DSANITIZER=address
cmake --build build-asan -j$(nproc)
./build-asan/tests
# or run the failing command

Thread errors:

rm -rf build-tsan
cmake -B build-tsan -S . -DSANITIZER=thread
cmake --build build-tsan -j$(nproc)
./build-tsan/tests

Valgrind (if ASan doesn't find it):

valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes \
  ./build/client --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk

Step 4: GDB Analysis

If the issue is a crash or hang:

gdb --args ./build/client [args...]
(gdb) run
# when it crashes:
(gdb) bt full
(gdb) info locals
(gdb) print variable_name

For hangs:

# In another terminal:
kill -SIGABRT <pid>  # generates core dump
gdb ./build/client core
(gdb) thread apply all bt

Step 5: Read the Code

Read the relevant source files around the crash/failure point. Look for:

Unchecked return values
Null pointer dereferences
Buffer overflows
Use-after-free
Race conditions
Incorrect protocol handling

Step 6: Diagnose Root Cause

Identify the exact file:line and what's wrong. Common patterns:

send_n_data / receive_n_data return value not checked
data_destroy() called but pointer still used
Queue operation without mutex in threaded code
Partial read/write not handled
Integer overflow in size calculations

Step 7: Fix

Apply the minimal fix. Don't refactor while debugging — one change at a time.

Step 8: Verify

# Rebuild and test
cmake -B build -S . && cmake --build build -j$(nproc)
./build/tests

# If integration test needed
python3 -m pytest tests/integration/ -n 4 --dist=load -m "not setpriv"

# Re-run under sanitizer to confirm fix
rm -rf build-asan
cmake -B build-asan -S . -DSANITIZER=address
cmake --build build-asan -j$(nproc)
# reproduce the original failing command

Step 9: Report

Print a summary:

=== DEBUG SUMMARY ===
Symptom: <what was happening>
Root cause: <file:line — what's wrong>
Fix: <what was changed>
Verification: <how it was confirmed fixed>

Rules

DO edit source files to fix issues
DO rebuild and test after fixes
DON'T refactor while debugging — minimal changes only
DON'T change behavior beyond fixing the bug
PRESERVE existing code style
ALWAYS verify with ./build/tests after changes

3.3 KiB Raw Blame History