Skip to content
Skills Library
Programming · Analysis

vbw-debug-target

/vbw-debug-target

Use when the user reports VBW misbehavior (pasted Claude Code session output, a command behaving wrongly, unexpected .vbw state). Resolves the contributor's local debug target repo first, never a guessed path, and names where Claude Code keeps the session, subagent, hook and debug logs to replay what happened.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the user reports VBW misbehavior (pasted Claude Code session output, a command behaving wrongly, unexpected .vbw state). Resolves the contributor's local debug target repo first, never a guessed path, and names where Claude Code keeps the session, subagent, hook and debug logs to replay what happened.

Original author description

Use when the user reports VBW misbehavior (pasted Claude Code session output, a command behaving wrongly, unexpected .vbw state). Resolves the contributor's local debug target repo first, never a guessed path, and names where Claude Code keeps the session, subagent, hook and debug logs to replay what happened.

How it works

SKILL.md has no level-two headings · 105 lines, 603 words

SKILL.md preview
---
name: vbw-debug-target
description: Use when the user reports VBW misbehavior (pasted Claude Code session output, a command behaving wrongly, unexpected .vbw state). Resolves the contributor's local debug target repo first, never a guessed path, and names where Claude Code keeps the session, subagent, hook and debug logs to replay what happened.
---

# Debugging VBW behavior

When the user reports VBW misbehavior — pasting Claude Code session output, describing incorrect command behavior, or showing unexpected file state — first resolve the contributor's **local debug target repo** instead of guessing a maintainer-specific path.

### Local debug target configuration (private, not committed)

Preferred setup in the VBW clone's shared Git common dir:

```text
$(git rev-parse --git-common-dir)/info/vbw-debug-target.txt
```

In a standard non-worktree clone, this usually resolves to:

```text
.git/info/vbw-debug-target.txt
```

The first non-empty, non-comment line must be the absolute path to the contributor's primary VBW consumer/test repo.
Relative paths are rejected so the resolver produces the same result regardless of the caller's current working directory.

Example local file content:

```text
/absolute/path/to/your-test-repo
```

This file lives under the clone's shared Git metadata, so it stays private and all worktrees created from that clone can read it automatically.

Legacy fallback for a single checkout only:

```text
.claude/vbw-debug-target.txt
```

That legacy file remains supported and gitignored, but it is scoped to one checkout/worktree and will not be copied into new worktrees.

Resolution order:
1. `VBW_DEBUG_TARGET_REPO` env var (one-off override, absolute path only)
2. `$(git rev-parse --git-common-dir)/info/vbw-debug-target.txt` in the current clone (preferred persistent local config, shared across worktrees)
3. `./.claude/vbw-debug-target.txt` in the current checkout/worktree (legacy fallback, absolute path only)
4. `<claude-config-dir>/vbw/debug-target.txt` (user-global fallback, absolute path only; `<claude-config-dir>` is resolved by `tools/resolve-claude-dir.sh`: `CLAUDE_CONFIG_DIR` if set, else `$HOME/.config/claude-code` when that directory exists, else `$HOME/.claude`)
5. If none are configured, **ask the user for the target repo path** — do not guess.

Use the shared resolver when debugging:

```bash
TARGET_REPO=$(bash tools/resolve-debug-target.sh repo)
TARGET_PLANNING=$(bash tools/resolve-debug-target.sh planning-dir)
ENCODED_PATH=$(bash tools/resolve-debug-target.sh encoded-path)
CLAUDE_PROJECT_DIR=$(bash tools/resolve-debug-target.sh claude-project-dir)
```

If the resolver exits non-zero, stop guessing and ask the user to configure a debug target.

### Claude Code Log Locations (canonical Claude config root)

In the paths below, `<claude-config-dir>` means the same Claude config root resolved by `tools/resolve-claude-dir.sh`: `CLAUDE_CONFIG_DIR` if set, else `$HOME/.config/claude-code` when that directory exists, else `$HOME/.claude`.

After resolving the target repo, derive the encoded Claude project path by replacing `/` with `-` in the absolute target-repo path. For an absolute path, the result begins with `-`.

Example rule:

```text
/absolute/path/to/project  ->  -absolute-path-to-project
```

When debugging, search these directories for evidence of what actually happened:

| Path | Contents | Use When |
| ------ | ---------- | ---------- |
| `<target-repo>/.vbw/` | Project state: `spec.md`, `record.json` (inspect with `vbw status` / `vbw show`) | Ground the investigation in actual workflow state |
| `<claude-config-dir>/projects/{encoded-path}/*.jsonl` | Session transcripts | Replaying what the LLM said/did in a session |
| `<claude-config-dir>/projects/{encoded-path}/{session-id}/subagents/agent-*.jsonl` | Subagent transcripts | Checking what VBW agent team members did |
| `<claude-config-dir>/projects/{encoded-path}/{session-id}/tool-results/` | Tool output snapshots | Seeing exact tool outputs from a session |
| `<claude-config-dir>/debug/{session-id}.txt` | Debug logs (`[DEBUG]`/`[WARN]`) | Startup issues, plugin loading, hook execution failures |
| `<claude-config-dir>/sessions/{pid}.json` | Active session metadata | Mapping a PID to a session ID |
| `<claude-config-dir>/session-env/{session-id}/` | Hook-exported env vars | Verifying `CLAUDE_SESSION_ID` and other env vars |
| `<claude-config-dir>/tasks/{session-id}/` | Task/subagent lock files | Checking for stuck or concurrent task issues |
| `<claude-config-dir>/settings.json` | User-level Claude Code settings and hooks | Verifying hook definitions, permissions, MCP config |

### Common search patterns

```bash
TARGET_REPO=$(bash tools/resolve-debug-target.sh repo)
CLAUDE_PROJECT_DIR=$(bash tools/resolve-debug-target.sh claude-project-dir)
CLAUDE_CONFIG_ROOT="$(dirname "$(dirname "$CLAUDE_PROJECT_DIR")")"

# Find sessions for the configured target repo
ls "$CLAUDE_PROJECT_DIR"/*.jsonl

# Search session transcripts for a VBW hook or command
grep -l 'vbw' "$CLAUDE_PROJECT_DIR"/*.jsonl

# Find hook errors in debug logs
grep -El 'hook.*error|hook.*fail' "$CLAUDE_CONFIG_ROOT"/debug/*.txt

# Search for a specific tool invocation across sessions
grep -Erl 'vbw (next|apply|prove|run start)' "$CLAUDE_PROJECT_DIR"/*.jsonl

# Check what a subagent did in a specific session
cat "$CLAUDE_PROJECT_DIR"/<session-id>/subagents/agent-*.jsonl
```

Versions

The database has no other skills named vbw-debug-target.

Database snapshot: 13.11.2026 · package version fd50bd3e40bf (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90vbw-review-contributor-pr
    Use when explicitly asked to review a contributor or external PR for VBW against the linked issue, an independent fix plan, local tests, QA evidence, and repo conventions. Submit a real GitHub PR review with inline code comments for anchorable findings; explicit invocation only.
  • 100vibe
    Take this VBW project to its next step (spec, plan, approve, build, prove, fix, accept, ship). Use it for any work on a VBW project.
  • 100debug-session
    Use when the user reports a bug, error, or unexpected behavior that needs investigation.
  • 100debug
    Debug errors and unexpected behavior with log analysis. Use for issues and error messages.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.