Skip to content
Skills Library
Programming · Analysis

wagoe-debug

/wagoe-debug

Diagnose a failure in a Wagoe app — a 500, an exception, a stack trace, a nil where a value was expected, a field that reads back empty, or a test that fails for no obvious reason. Use when something in a Wagoe project is broken and the cause is not yet known. Works from the innermost layer outward, checks the framework's known pitfalls first, and can call bb ai explain on a stack trace.

Repository
wagoe ↗
Licence
EPL-2.0
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

EPL-2.0, otwarta.

What it does and when to use it

Diagnose a failure in a Wagoe app — a 500, an exception, a stack trace, a nil where a value was expected, a field that reads back empty, or a test that fails for no obvious reason. Use when something in a Wagoe project is broken and the cause is not yet known. Works from the innermost layer outward, checks the framework's known pitfalls first, and can call bb ai explain on a stack trace.

Original author description

Diagnose a failure in a Wagoe app — a 500, an exception, a stack trace, a nil where a value was expected, a field that reads back empty, or a test that fails for no obvious reason. Use when something in a Wagoe project is broken and the cause is not yet known. Works from the innermost layer outward, checks the framework's known pitfalls first, and can call bb ai explain on a stack trace.

How it works

  1. Symptom → likely cause
  2. Work from the inside out
  3. Logs — check where they actually go first
  4. bb ai explain
  5. Steps
  6. What this does not cover
Original SKILL.md headings · 124 lines, 800 words
SKILL.md preview
---
name: wagoe-debug
description: Diagnose a failure in a Wagoe app — a 500, an exception, a stack trace, a nil where a value was expected, a field that reads back empty, or a test that fails for no obvious reason. Use when something in a Wagoe project is broken and the cause is not yet known. Works from the innermost layer outward, checks the framework's known pitfalls first, and can call bb ai explain on a stack trace.
---

# Wagoe — debugging

Most Wagoe bugs are one of a handful of shapes. Check those before reasoning
from first principles — it is usually faster, and the symptoms are distinctive.

## Symptom → likely cause

| Symptom | Look at |
|---|---|
| A field reads back `nil` for no reason | snake_case / kebab-case mismatch |
| A new field is missing or rejected | schema, column and persistence transform out of sync |
| Generic 500 with "Exception reached HTTP boundary" | `ex-info` without `:type` in ex-data |
| A route answers at `/api/v1/api/…`, or not at all | module routes wrote the prefix themselves, or returned a flat vector instead of a `{:api :web :static}` contribution |
| `No matching method` on a Java call | static vs instance interop |
| `Unable to resolve symbol` for your own fn | private helper defined below its caller |

### The nil one is worth recognising on sight

kebab-case everywhere in Clojure; snake_case **only** at the database boundary;
camelCase **only** at the API boundary. Use `:created_at` internally and the
lookup silently returns nil — no error, no warning, just a missing value. In a
test it shows up as:

```
Expected:  #<java.time.Instant … 2026-01-01T00:00:00Z>
Actual:    -#<java.time.Instant …> +nil
```

That `+nil` against a concrete expected value is the signature. Note the
quality gates do **not** catch this — `bb check` passes on a project with this
defect, because a wrong keyword is still a valid keyword. Only a test that
exercises the value finds it.

## Work from the inside out

Do not debug through the whole stack. Find the innermost layer that is wrong:

1. **Core** — pure functions. Call them directly in a REPL with the failing
   input. No database, no HTTP. If they are wrong, stop here.
2. **Persistence** — query the database directly and compare with what the
   entity looks like after transformation. This is where case mismatches show.
3. **Service** — call the port function with a stub repository.
4. **HTTP** — only once the layers beneath are known good.

```clojure
;; in the REPL, after (go)
(def svc (get integrant.repl.state/system :wagoe/user-service))
(def ds  (get-in integrant.repl.state/system [:wagoe/db-context :datasource]))
(jdbc/execute! ds ["SELECT * FROM users LIMIT 5"])
```

Reload with `(reset)`. After changing a `defrecord`, `(reset)` is not enough —
it reuses the old instances. Use `(halt)` then `(go)`.

## Logs — check where they actually go first

**A generated project ships no logback config**, so there is no log file to
tail. Logback falls back to console, which means the stack trace is in the
terminal running `clojure -M:run` or in the REPL — not on disk. Looking for a
file and finding none is not evidence that nothing was logged.

```bash
find . -name "logback*.xml"     # nothing? then logs are on the console
```

In the Wagoe framework repository itself, `resources/logback.xml` writes to:

| | |
|---|---|
| `logs/wagoe.log` | application, including stack traces |
| `logs/audit.log` | audit trail |
| `logs/security.log` | security events |

```bash
tail -100 logs/wagoe.log | grep -A 10 "ERROR"
```

If a project has added its own logback config, read that file for the path
rather than guessing.

`println` goes to stdout, not to any log file — and should come out before
committing.

## `bb ai explain`

```bash
bb ai explain --file stacktrace.txt
cat stacktrace.txt | bb ai explain
```

It needs an AI provider:

```bash
bb doctor:env      # names the provider that would be used, or says none is set
```

The failure modes are readable now (BOU-280). With nothing configured it says
so and lists the variables to set; a rejected key says the key was rejected
rather than printing the request map; an exhausted balance is distinguished
from rate-limiting, because the advice differs. If you see a raw stack trace
from `bb ai`, that is a bug worth filing, not a configuration hint.

This is an accelerator, not the method. The symptom table and layer isolation
above work with no provider at all.

## Steps

1. Get the actual error — full text, not a paraphrase. A stack trace, a test
   diff, or a response body.
2. Match it against the symptom table.
3. Identify the innermost layer that could produce it, and test that layer
   directly.
4. Fix, then re-run the thing that failed. If a test caught it, that test is
   your verification.
5. If nothing matched, `bb ai explain` on the trace — provider permitting.

## What this does not cover

`bb check` and the test suite catch structural problems: FC/IS violations,
missing ports, untagged tests, lint. They do not catch logic errors, and as
above they do not catch case mismatches. A green `bb check` on a broken app is
normal and means nothing about correctness.

Versions

The database has no other skills named wagoe-debug.

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

  • 100wagoe-doctor
    Diagnose and fix a Wagoe project's configuration and development environment. Use when a Wagoe app will not start, when config.edn changes are not taking effect, before running dev commands on an unfamiliar machine, when JWT_SECRET or database settings look wrong, or when the…
  • 100wagoe-scaffold
    Generate a Wagoe module, field, endpoint or adapter with the correct FC/IS structure, then wire it in and verify the quality gates pass. Use when adding a feature, entity, domain concept, REST endpoint or port implementation to an existing Wagoe project — for example "add a…
  • 90roblox-debug
    Debug Roblox errors - Output messages, stack traces, "attempt to index nil", "Infinite yield possible", require errors, scripts that don't run, replication issues. Use when the user pastes an error, says something "doesn't work", or a play test shows errors.
  • 86debug
    Trace a bug, error, or regression to its root cause. Use when investigating a failure, a stack trace, unexpected behavior, or "why does X happen".
  • 95debugging
    Use when debugging bugs, test failures, or unexpected behavior. Triggers: 'why isn't this working', 'this doesn't work', 'X is broken', 'something's wrong', 'getting an error', 'exception in', 'stopped working', 'regression', 'crash', 'hang', 'flaky test', 'intermittent…
  • 100debugging
    Finds and fixes bugs through systematic root cause analysis, stack trace interpretation, browser DevTools automation, CI/CD pipeline debugging, performance profiling, test pollution detection, and AI-powered error analysis. Use when the user asks to debug, fix a bug, investigate…

Feedback and reports

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