Guide

Evidence-preserving debugging briefs

A useful debugging brief is not the shortest possible paste. It is the smallest reviewed prompt that still contains the command, failure type, root-cause evidence, and verification request.

tokensift renders briefs in a conservative shape so the reviewer can see what was kept and what was folded. Use this guide to judge whether the brief is ready for Codex, Claude Code, ChatGPT, OpenCode, or another coding agent.

Open the main Sift tool Review checklist

What counts as evidence

Evidence is any line that constrains the likely fix. Repeated status output is rarely evidence. The line that says exactly what failed usually is.

Keep

  • The command that produced the failure, including flags that change behavior.
  • The primary error line, exception, assertion, TS code, package error, or exit code.
  • The nearest user-owned file, test, Dockerfile, config, or source location.
  • Expected and received values when the failure is an assertion or type mismatch.
  • Memory, version, platform, package-manager, or environment lines when they explain the failure.
  • A short manual note for recent changes that are not visible in the log.

Fold

  • Progress bars, transfer progress, and repeated timestamp-only lines.
  • Duplicate warnings that repeat the same text.
  • Dependency stack frames after the user-owned call site is clear.
  • Successful cached layers, passing test progress, and asset output.
  • Long captured logs that do not change the assertion, exception, or exit code.
  • Terminal history before the command that triggered the failure.

Brief structure

A reviewed brief should answer four questions before the coding agent reads it: what failed, what evidence proves it, what noise was removed, and what the agent should do next.

Template

Debug [failure type].

Type:
- [detected parser route and confidence if available]

Keep:
- cmd: [command that produced the failure]
- frame: [nearest user-owned file, test, Dockerfile, or source location]
- error: [primary exception, assertion, package error, TS code, or exit line]
- detail: [one to six details that constrain the fix]
- env: [version, memory, platform, or package-manager context when relevant]

Folded:
- [named groups of repeated or low-signal output]

Ask: root cause, smallest fix, verify command.

Verified example

This example is an excerpt from a raw failure log, not a setup command to run. It was checked against the current tokensift parser output.

Before: raw pytest excerpt

$ pytest tests/test_api.py::test_creates_user -q
=================================== FAILURES ===================================
______________________________ test_creates_user _______________________________
tests/test_api.py:37: in test_creates_user
    assert response.status_code == 201
E   assert 500 == 201
E    +  where 500 = <Response [500]>.status_code
------------------------------ Captured log call -------------------------------
INFO app db retry 1
INFO app db retry 2
=========================== short test summary info ===========================
FAILED tests/test_api.py::test_creates_user - assert 500 == 201

After: conservative brief

Debug pytest failure.

Type:
- pytest (high confidence)

Keep:
- cmd: pytest tests/test_api.py::test_creates_user -q
- frame: tests/test_api.py:37 — in test_creates_user
- error: FAILED tests/test_api.py::test_creates_user - assert 500 == 201
- assertion: assert response.status_code == 201
- assertion: E   assert 500 == 201
- assertion: E    +  where 500 = <Response [500]>.status_code

Folded:
- captured logs x4

Ask: root cause, smallest fix, verify command.

Review checklist before sharing

  • Does the brief include the command or test target that produced the failure?
  • Does the primary error line still include the exact exception, assertion, TS code, package name, memory number, or exit code?
  • Does at least one retained line point to user-owned code, a test, Dockerfile, config, or build command?
  • Does the brief avoid inventing a root cause that the log does not prove?
  • Are secrets, internal URLs, credentials, customer data, private paths, and unnecessary source excerpts removed or replaced?
  • Does the final ask request the root cause, smallest fix, and verification command?

Common mistakes

  • Over-compressing: removing the one file path or assertion line that makes the failure actionable.
  • Under-compressing: pasting hundreds of repeated progress lines that dilute the actual error.
  • Turning evidence into opinion: telling the agent the fix before showing the line that proves the failure.
  • Omitting the run target: leaving out the exact command, test node id, Docker build command, or package manager invocation.
  • Hiding uncertainty: failing to mention when the log is incomplete, truncated, or missing project context.

Limits

An evidence-preserving brief cannot replace the source code, dependency graph, test fixtures, runtime environment, or CI secrets policy. It only gives the coding agent the best compact view of the failure evidence you chose to share.

Use a longer prompt when the failure depends on state outside the log: a recent migration, a feature flag, a generated file, a mock server, a private package registry, or a non-obvious deployment environment.

Submission storage boundary

When a visitor clicks the Sift button on the backend-hosted deployment, tokensift stores the submitted raw input, generated output, user IP address, user agent, and KST timestamp in a private SQLite database controlled by tokensift. Backend-hosted raw submissions in SQLite and private operator JSONL preview logs are retained for up to 30 days by default for diagnostics and parser improvement. Raw logs are not sent to analytics or ads.

Related documents

How tokensift worksThe normalize, redact, detect, parse, render, and metric pipeline. Supported log typesEvidence preserved and folded for each parser route. Preparing logs for coding agentsHow to capture bounded failure context before using the tool. Privacy policyCollection, retention, deletion, analytics, and ads details.