Reports

A report tells the warden maintainers about a problem with warden itself, and its status comes back to your project.

Reports are about warden, not about your code: a gate that blocked for no reason, a confusing message, a missing feature that every project would want. Problems in your own code, tools or setup belong in your own tickets, .warden/rules/ or .warden/knowledge/.

Sending a report#

Ask the project's agent to run /warden:report, or run the command yourself:

warden report --kind bug --title "Gate blocks after a clean merge" --body "What happened: ... Expected: ... Steps: ... Evidence: ..."

A good body says what happened, what you expected, the steps to repeat it, and the evidence (the exact message or command output). Keep repository names, links, secrets, credentials and customer data out of it.

The command prints {"id":"R-eb85-0001","status":"sent"}. The id has two parts: four characters that name your machine, and a number. So reports from several machines in one project never clash.

Warden also files a report by itself when the fixer finds that warden is at fault (a WARDEN_BUG result). See Gates and self-healing.

Where a report goes#

1. The report is saved on your machine, in the reports/ folder of the warden data folder (by default ~/.claude/plugins/data/warden-warden-marketplace/reports/).
2. A row is added to .warden/reports.md in the main checkout, also when the command runs in a task worktree. This table is committed, so your team sees the reports too.
3. A background sync sends the report to the warden maintainers with git, and fetches status updates back. It runs after each report, and from session start about once an hour. Run it now with warden report sync.

The sync needs write access to the warden repository. Without it, reports stay on this machine, and session start tells the agent once: "reports from this machine reach warden only on this machine".

Committing .warden/reports.md#

The /warden:report skill commits the new row on the main checkout, only when it is on the main branch and nothing else is staged there. It never switches branches and never pushes unless you ask. Never commit the row on a task branch.

Statuses#

fixed and wontfix are closed. The others are open.

warden report --status          # open reports: id, title, status, fixedIn, note; plus a count of closed ones
warden report --status --all    # every report of this project
warden report --status --write  # rewrite .warden/reports.md from the latest statuses; prints only counts

Questions from the maintainers#

When the maintainers need more information, a report moves to needs-info with a question. A report gets at most three questions.

• Usually it is answered at once, by itself. When the project's main checkout is on the machine that filed the report, warden starts a headless, read-only Claude run there. It looks at the project's code, config, .warden files, logs and git history, may run warden status and read-only git commands, changes nothing, and answers with warden report reply. The report goes back to sent.
• Otherwise the question waits. That happens for a report filed on another machine, filed before warden 0.5, or when the answer run could not start. Session start then shows the question with the command to answer it.

To answer by hand, from the project:

warden report reply R-eb85-0001 --body "The check was bun test; the log line was ..."

The answer is one argument (or --file <path>), at most 4000 characters. Keep secrets, credentials and customer data out of it. reply fails when the report has no open question.

What session start tells you#

Every new session (and every resume, clear or compact) starts with a few lines from warden. They are notes for the project's agent; most say to wait until your current request is done.

Each report status change is told once per main checkout.

See also#

• Checks and retro
• Upgrading
• Skills reference
• CLI reference
• FAQ