output-template

Output templates

Two templates: Debug Report (targeted mode, posted as an issue comment) and Triage Report (sweep mode, printed to stdout). Plus the Verification Spec block embedded inside the Debug Report.

Debug Report (targeted mode)

Use this template verbatim. Each section is required; mark "n/a" if a section truly doesn't apply (rare).

## Debug Report — Issue #<N>: <Title>

_Generated by `/debug <N>` at <UTC timestamp>. Walked all 8 steps; see below._

### Classification
- **Class**: <one of 15 from step-classify.md>
- **Secondary class** (if any): <or "none">
- **Severity**: <severity:critical | severity:major | severity:minor | severity:trivial>  _(per ~/.claude/commands/monitor/severity-rubric.md)_
- **Matches systemic pattern?**: <Yes → #XXX (name from systemic-patterns.md) | No → novel | By-design — STOP, no fix>
- **Affected version(s)**: <e.g. v0.35.3rc14–rc19>
- **Affected host(s)**: <lba-1 / nsd / channelo / mac / fleet-wide>

### Evidence gathered (Step 2)

- **journalctl**: <findings — quote 2-5 lines, truncate at 200 chars each>
- **structlog event signatures matched**: <list with counts>
- **State files inspected**: <files + relevant deltas>
- **Telegram chat history**: <chat_id + relevant message snippets, or "n/a">
- **Fleet probe**: <per-host result; mark unreachable hosts explicitly>
- **Per-host PyPI version**: <table if version-skew relevant, else "uniform across fleet">
- **Pytest reproduction**: <test command + result, or "not attempted because <reason>">
- **Git regression**: <commits in the suspected range, e.g. `git log v0.35.3rc13..v0.35.3rc14 -- src/untether/<area>/`>
- **CHANGELOG correlation**: <relevant entries, with version + section>

### Research conducted (Step 3)

- **Untether docs**: <specific docs + sections cited>
- **Closed Untether issues (last 90d)**: <relevant numbers + outcomes>
- **Upstream engine repo**: <upstream issue numbers, or "no relevant upstream issue found">
- **Library issues (anyio/msgspec/structlog/httpx)**: <if relevant>
- **Memory notes consulted**: <e.g. `feedback_cron_plan_mode_stalls`, `project_channelo_rc15_dead_wakeup_507_redux`>

### Systemic pattern check (Step 4)

<exact pattern name from systemic-patterns.md, OR "no match — novel issue">

If match: <whether posture is `bug` / `regression-watch` / `by-design` / etc.,
and the implication for this specific issue>

### Hypothesis (Step 5)

**Hypothesis**: <root cause stated as cause → effect>

**Supporting evidence**: <log lines, file references, doc citations — cite Step 2 + 3 outputs>

**Ruled out**: <alternatives investigated and dismissed, with reason>

**Prior confidence**: <0–100%>  _(recorded BEFORE testing)_

**Pre-mortem (if confidence <80%)**: <if the fix fails in 48h, the most likely reason is...>

### Verification (Step 6)

- **Reproduction**: <stub-subprocess test path | live repro on @untether_dev_bot | journalctl observation | "could not reproduce — see hypothesis">
- **Doc support**: <specific docs / rule files / changelog entries>
- **Closed-issue prior fixes**: <relevant fix SHAs or "none found">

### Fix (Step 7)

**Files touched**: <list with line ranges>

**Change summary**: <one paragraph: what changes, why this fixes it, why it's minimal>

**Commit / PR**: <commit SHA | PR URL once opened; or "PR pending — awaiting approval">

**Test results**:
- Targeted: `uv run pytest tests/test_<area>.py -x` → <pass/fail + count>
- Full suite: `uv run pytest` → <pass/fail + count>
- Lint: `uv run ruff check src/` → <clean/diagnostics>
- Format: `uv run ruff format --check src/ tests/` → <clean/needs-format>

**CHANGELOG**: <quoted entry with issue link>

### Verification Spec (for follow-up verification)

- **Verify-After**: <YYYY-MM-DD; default fix-merge-date + 2 days>
- **Verification criteria**: <plain-English success definition>
- **Falsification criteria**: <what would prove the fix is NOT working — REQUIRED>
- **Data source hints**: <one or more from the Untether vocabulary below>
- **Min-Samples**: <integer; gate against low-traffic false-PASS>
- **Min-Traffic-Hours**: <integer; INCONCLUSIVE until this many hours of normal-volume traffic>
- **Baseline**: <pre-fix metric value, if measurable>
- **Target**: <post-fix target>

#### Untether Verification Spec vocabulary

- `journalctl:event=<event_name>` — absence/count of a specific structlog event in journalctl
- `journalctl:level=error` — error-level lines in journalctl
- `gh_issues:label=<label>` — count of issues with a label
- `pytest:tests/test_<X>.py::test_<Y>` — specific pytest passes
- `attestation:integration-test-pass-${VERSION}.json` — marker exists for VERSION
- `telegram_chat:<chat_id>` — observation in a specific chat
- `proc_diag:<field>` — proc_diag field value (e.g. `proc_diag:cpu_active=true`)
- `fleet_rollout:${VERSION}` — version uniform across 5 hosts
- `cost_tracker:peak_idle_seconds` — cost-tracker metric thresholds

### Prevention (Step 8 + future)

<test additions / hook additions / monitoring additions / runbook additions / config exposures that would have prevented or quickly surfaced this>

---
🤖 Generated by `/debug` — see `.claude/commands/debug/` for protocol detail