Skip to content
Skills Library
Programming · Building & coding

bunqueue-fixing-bugs

/bunqueue-fixing-bugs

Runs the bunqueue reproduce-first bug workflow. Use when a bug, regression, crash, wrong result, data loss, hang or flaky behavior is reported in bunqueue (server, client, workflow engine, CLI, MCP, SDKs), when a GitHub issue describes a defect, or when a skeptic, model-campaign or CI finding needs a fix. Covers the regression test that fails first, subagents that prove the fix, docs and changelog in the same change, the gates, and skeptic rounds until PASS. Not for features without a defect, or for only running the gates (bunqueue-running-gates).

Repository
bunqueue ↗
Licence
MIT
Last repository change
13.11.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
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.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

Runs the bunqueue reproduce-first bug workflow. Use when a bug, regression, crash, wrong result, data loss, hang or flaky behavior is reported in bunqueue (server, client, workflow engine, CLI, MCP, SDKs), when a GitHub issue describes a defect, or when a skeptic, model-campaign or CI finding needs a fix. Covers the regression test that fails first, subagents that prove the fix, docs and changelog in the same change, the gates, and skeptic rounds until PASS. Not for features without a defect, or for only running the gates (bunqueue-running-gates).

Original author description

Runs the bunqueue reproduce-first bug workflow. Use when a bug, regression, crash, wrong result, data loss, hang or flaky behavior is reported in bunqueue (server, client, workflow engine, CLI, MCP, SDKs), when a GitHub issue describes a defect, or when a skeptic, model-campaign or CI finding needs a fix. Covers the regression test that fails first, subagents that prove the fix, docs and changelog in the same change, the gates, and skeptic rounds until PASS. Not for features without a defect, or for only running the gates (bunqueue-running-gates).

How it works

  1. 1. Reproduce: the test comes first
  2. 2. Fix with subagents, judged by the test
  3. 3. Prove it
  4. 4. Docs and changelog in the same change
  5. 5. Gates
  6. 6. Skeptic rounds until PASS
  7. Gotchas
Original SKILL.md headings · 123 lines, 1,022 words
SKILL.md preview
---
name: bunqueue-fixing-bugs
description: "Runs the bunqueue reproduce-first bug workflow. Use when a bug, regression, crash, wrong result, data loss, hang or flaky behavior is reported in bunqueue (server, client, workflow engine, CLI, MCP, SDKs), when a GitHub issue describes a defect, or when a skeptic, model-campaign or CI finding needs a fix. Covers the regression test that fails first, subagents that prove the fix, docs and changelog in the same change, the gates, and skeptic rounds until PASS. Not for features without a defect, or for only running the gates (bunqueue-running-gates)."
license: MIT
metadata:
  short-description: Reproduce, fix and prove a bunqueue bug
---

# Fixing a bunqueue bug

The rules this procedure serves live in [CLAUDE.md](../../../CLAUDE.md) and
[AGENTS.md](../../../AGENTS.md): reproduce before fixing, gates before a commit, the
skeptic before every commit and push, docs and changelog in the same change, and
nothing is committed or pushed without the user's explicit request. This skill is the
order of work and the traps found in real sessions.

Start the session first (bunqueue-working-sessions): one work item, `in-progress`,
with its branch.

## 1. Reproduce: the test comes first

1. Write the regression test before touching runtime code. Name it after the issue or
   symptom: `test/repro-issue-<n>-<topic>.test.ts`; a model-campaign finding becomes
   `test/repro-model-<topic>.test.ts`.
2. Drive the public or real persistence path (Queue/Worker over TCP or embedded, a real
   SQLite file) and assert both the returned result and every counter or state the bug
   corrupts. A unit test of a private helper passes even when the wiring is broken.
3. Run it on the unfixed code and read the failure:

   ```bash
   BUNQUEUE_EMBEDDED=1 bun test test/repro-issue-<n>-<topic>.test.ts
   ```

   It must fail on the assertion that describes the bug. A typo, a missing import, a
   timeout, a port clash or a setup error is a failure for the wrong reason and proves
   nothing; fix the test until the failure message names the bug. Keep that output: the
   Definition of Done asks for a test that failed before the fix.
4. Follow the test hygiene of [docs/testing.md](../../../docs/testing.md#test-hygiene):
   fresh server, `port: 0`, unique queue names and temporary SQLite paths, closed
   clients, polling with a deadline instead of fixed sleeps.

## 2. Fix with subagents, judged by the test

- Brief each subagent like a peer: the failing test path and its output, the files that
  are likely involved, what is ruled out, and the constraints (scope, 300 lines per
  file, the lock hierarchy, no `await` inside a shard critical section). Ask for the
  smallest change that makes the test pass without editing the test. Templates for
  this brief and the skeptic's: [references/briefs.md](references/briefs.md).
- When the cause is unclear, let two or three subagents try different hypotheses in
  parallel and choose by evidence: the regression test, the neighbouring test files,
  and the model campaign when it applies.
- Never weaken or rewrite the reproducing test to make it pass. If the test itself was
  wrong, fix it and show again that it fails on the unfixed code.
- Keep the fix compatible: change the broken behavior only. Anything else a user could
  observe (a default, a signal, a log line, an error message) is a behavior change that
  needs its own decision and, at release time, an Upgrade notes entry.

## 3. Prove it

```bash
BUNQUEUE_EMBEDDED=1 bun test test/repro-issue-<n>-<topic>.test.ts   # now passes
BUNQUEUE_EMBEDDED=1 bun test test/<neighbouring files>.test.ts       # still pass
bun run typecheck
bun fmt --check --no-script src test
git diff --check
```

Run `bun run test:model` first when the change touches anything on its trigger list
in [CLAUDE.md](../../../CLAUDE.md#mandatory-gates). Iterate in an isolated OrbStack
development Machine where you can; a macOS-host run is diagnostic only, and the gates
are the sandbox and the Machine gate (step 5).

## 4. Docs and changelog in the same change

- The module's `docs/features/<slug>.md`, plus [docs/data-model.md](../../../docs/data-model.md)
  for a type, table, TCP command, endpoint, env var or default, and
  [docs/architecture.md](../../../docs/architecture.md) for a data-flow change.
- An entry under the `## [Unreleased]` heading of
  [the changelog](../../../docs/src/content/docs/changelog.md), in its `### Bug fixes`
  subsection (add the subsection if the section has none yet): the user-visible
  symptom, the cause, the fix, and any behavior change. Numbers only from real
  measurements.

## 5. Gates

Follow bunqueue-running-gates: `bun run test:sandbox` after any code change (about
9 minutes; run it in the background), `bun run test:sandbox:sdk` when `sdk/` changed,
and the final Linux validation in a fresh Ubuntu 24.04 Machine
(bunqueue-running-machine-gates).
Record the gated tree with `git write-tree` and review `summary.md`, not just the exit
code.

## 6. Skeptic rounds until PASS

1. Stage the complete change first: the skeptic reads `git diff --staged`, so an
   unstaged hunk is invisible to it.
2. Invoke the `skeptic` subagent (profiles `.claude/agents/skeptic.md` and
   `.codex/agents/skeptic.toml`) with the bug, the reproducing test and its
   before/after output, the gate results and their artifact paths.
3. `FAIL`: fix every concern, rerun what it touches (the gate too, if code changed),
   and invoke it again. `CONDITIONAL`: fix what you can; the rest needs the user's
   explicit confirmation. `PASS`: commit only if the user asked for a commit.
4. Expect more than one round. Past rounds found real defects every time: a server
   started under `nohup` that a new `SIGHUP` handler changed from "ignored" to
   "reloads", a Docker restart policy that treats `docker kill -s HUP` as a manual stop,
   a rebound unix socket that lost its mode and owner, and log lines that claimed more
   than had happened. Answer a concern with a test or a fix, not an argument.
5. After the last fix, the gate evidence must describe the final staged tree; prove any
   later delta (bunqueue-running-gates).

## Gotchas

- `git stash` is shared by every worktree of the repository; another session can pop
  your entry. Set work aside with a temporary commit instead.
- A test that reads a new root-level file (a fixture, a config) passes on the host and
  fails in the sandbox with `ENOENT` unless [Dockerfile.test](../../../Dockerfile.test)
  copies it and `Dockerfile.test.dockerignore` allow-lists it. `test/` itself is copied.
- To show that an edited reproducing test still fails on the old code, run it in a
  temporary `git worktree add --detach <dir> HEAD` with the test copied in and
  `node_modules` symlinked, then `git worktree remove <dir>`; never revert files in
  the shared worktree.
- Bun discovers test files in readdir order, which differs between macOS and Linux; a
  leaked embedded manager or timer shows up as a failure in a different file. Close
  every Queue, Worker and manager, and claim the singleton with
  `beforeAll(shutdownManager)` in suites with a persistent `dataPath`.
- A fix found while fixing something else is a new `not-started` item in
  `feature_list.json`, not part of this change.
- A host-only green run is diagnostic. The Linux sandbox has caught failures the macOS
  host passed (package layout, readdir order, missing files in the image).
Files in this package (3)
  • SKILL.md 7 KB
  • evals/evals.json 6 KB
  • references/briefs.md 3 KB

Versions

The database has no other skills named bunqueue-fixing-bugs.

Database snapshot: 13.11.2026 · package version b944199b57f6 (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

  • 100bunqueue-running-gates
    Selects, runs and reads the bunqueue validation gates. Use when about to commit a bunqueue change or asked which gate it needs, when bun run test:sandbox, test:model or test:sandbox:sdk fails or shows anomalies, when a test passes on the host but fails in the container, when…
  • 100bunqueue-working-autonomously
    Use only when the user explicitly asks for bunqueue work to proceed autonomously in a local session: to keep going through the work items unattended, to run the autonomous loop, or to start it with /loop. Runs one feature_list.json item at a time, each on its own branch and…
  • 100hatch3r-bug-fix
    Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
  • 100bug-fix-tdd
    Reproduce and fix bugs using TDD. Use when analyzing a bug report, writing a regression test, or applying a minimal fix. Covers test placement, mock patterns, and the red-green-refactor workflow for automated bug fixing.
  • 100bug-fix
    Bug fix workflow. Use when: fixing bugs, resolving issues, regression fixes. Not for: new features (use feature-dev), understanding code (use code-explore). Output: fix + regression test + review gate.
  • 100fix-bug
    Diagnoses and fixes bugs using a test-first workflow (reproduce, diagnose, fix). Use this skill whenever the user reports a bug, describes unexpected behavior, or asks to investigate or fix a defect. Even if the user says "something's broken", "this isn't working", "fix this…

Feedback and reports

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