20 added, 32 removed. Audit A to A.
---
name: debug
- description: >
- Investigate and fix bugs in AgentSync's Bash scripts or sync logic.
- USE WHEN debugging sync failures, YAML parsing issues, cross-platform errors, or bats test failures.
+ description: Investigate and fix bugs, errors, or unexpected behavior systematically — reproduce, locate, understand the root cause, fix it, and add a regression test. Use this skill when the user reports a failure (test, runtime, build, CI), shares a stack trace or error message, says something doesn't work, asks why something is broken, or asks for a fix that requires diagnosis — even when the word "debug" is not used (e.g. "this is broken", "почему падает", "не работает X").
---
- # Debug AgentSync
+ # Debug
- Systematically find and fix bugs in the sync engine or helpers.
+ Systematically find and fix the root cause of a bug.
## Steps
- 1. **Reproduce** — Get the exact error. Run the failing command with `bash -x` for trace output:
- - `bash -x bin/agentsync.sh sync` for sync issues.
- - `bats tests/<file>.bats` for test failures.
- - Check CI logs if the failure is platform-specific.
- 2. **Locate** — Narrow down the failing script:
- - `bin/agentsync.sh` → CLI entry point, delegates to helpers.
- - `lib/sync.sh` → Main sync engine.
- - `lib/helpers/*.sh` → Specific functionality (YAML parsing, file ops, gitignore, etc.).
- - `lib/helpers/yaml.sh` → Custom YAML parser (common source of parsing bugs).
- 3. **Understand** — Check:
- - Is it a portability issue? (macOS vs Linux vs Git Bash)
- - Is the YAML parser mishandling a value? (Quoting, comments, nesting)
- - Is a file path wrong? (Relative vs absolute, symlink resolution)
- - Is `set -euo pipefail` causing an unexpected exit? (Unset variable, failed command)
- 4. **Fix** — Make the smallest portable change. Test on the affected platform.
- 5. **Verify** — Run the specific bats test file, then the full suite: `bats tests/`.
-
- ## Common Issues
-
- - **`unbound variable`** — Missing `${VAR:-}` default for optional variables under `set -u`.
- - **`sed` differences** — macOS BSD sed vs GNU sed. Avoid `sed -i`, write to temp + `mv`.
- - **Path issues** — Use `cd && pwd` pattern, not `realpath` or `readlink -f`.
- - **YAML parsing** — The custom parser only handles `key: value`. No arrays, no multiline blocks.
+ 1. **Reproduce** — Get the exact error message, stack trace, or steps to reproduce. Understand what happens vs. what should happen.
+ 2. **Locate** — Narrow down where the problem is:
+ - Read the error message and stack trace — they usually point to the exact location.
+ - Search for relevant keywords (error strings, function names).
+ - Trace the data flow from input to the failure point.
+ 3. **Understand** — Before fixing, understand *why* it fails:
+ - What assumption is violated?
+ - When was it introduced? (`git log`, `git blame`)
+ - Logic error? Data problem? Race condition? Missing edge case?
+ 4. **Fix** — Make the smallest change that correctly addresses the root cause.
+ 5. **Verify** — Write or update a test that catches this bug. Run the full test suite for regressions.
+ 6. **Explain** — Briefly describe what caused it and why the fix is correct.
## Gotchas
- - Don't add `set +e` to silence errors — find the actual failing command.
- - Platform-specific bugs often manifest only in CI — check all three OS results.
- - The `example/` directory is a full integration test — run `agentsync sync` there to validate end-to-end.
- - YAML values with `#` are treated as comments unless quoted. Check `_yaml_normalize_scalar` for edge cases.
+ - Don't wrap the error in try-catch to silence it — that's hiding, not fixing.
+ - Don't fix symptoms without understanding the cause.
+ - Don't make speculative changes ("maybe this will fix it") — understand first.
+ - Don't change multiple things at once — isolate the fix so you know what worked.
+ - Don't assume the bug is where the error is thrown — trace upstream to the root cause.