[DOCS] /debug command docs outdated — does not reflect mid-session toggle behavior
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/slash-commands
Section/Topic
/debug command description
Current Documentation
slash-commands.md describes /debug as:
* **/debug [description]**: troubleshoots your current Claude Code session by reading the session debug log. Optionally describe the issue to focus the analysis.features-overview.md lists /debug as a bundled skill alongside /simplify and /batch, with no description of its current behavior.
cli-reference.md documents the --debug CLI flag (category filtering for startup) but does not cross-reference the /debug slash command or its mid-session toggle.
What's Wrong or Missing?
The changelog entry for v2.1.71 states:
"Updated /debug to toggle debug logging on mid-session, since debug logs are no longer written by default"
The current documentation describes /debug as a command that reads the session debug log. This is now outdated: the primary function of /debug has changed. Debug logs are no longer written by default, so there is nothing to read until /debug is invoked to toggle logging on for the current session.
The behavior change has two parts that need documenting:
- Debug logs are off by default — previously they were written to disk continuously; now they are not.
/debugtoggles debug logging on for the current session — rather than reading a pre-existing log, the command enables log writing from that point forward.
Users following the old description ("reads the session debug log") will find it does not match actual behavior. Users trying to diagnose issues who expect a debug log file to exist will be confused when none exists.
Suggested Improvement
Update the /debug entry in slash-commands.md:
Before:
* **/debug [description]**: troubleshoots your current Claude Code session by reading the session debug log. Optionally describe the issue to focus the analysis.After:
* **/debug**: Toggles debug logging on for the current session. Debug logs are not written by default; run/debugmid-session to enable them. Useclaude --debugat startup to enable debug logging from the beginning of a session.
Also update features-overview.md if it contains a description of /debug.
Add a cross-reference from the --debug CLI flag entry in cli-reference.md to the /debug slash command, noting the distinction (startup vs. mid-session).
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/slash-commands | /debug description is stale |
| https://code.claude.com/docs/en/cli-reference | --debug flag has no cross-reference to mid-session toggle |
Total scope: 2 pages affected
Source: Changelog v2.1.71
Exact changelog entry:
"Updated /debug to toggle debug logging on mid-session, since debug logs are no longer written by default"
4 Comments
Still relevant as of 2026-03-28 after re-checking the current docs. This issue is partially resolved, but the remaining documentation gap is still present.
---
Issue #31680 Verification
Title: [DOCS] /debug command docs outdated — does not reflect mid-session toggle behavior
Issue Date: 2026-03-07
Verification Date: 2026-04-01
Status: PARTIALLY RESOLVED
---
Issue Summary
This issue reports that the
/debugdocumentation described the command as reading an existing session debug log even though the v2.1.71 changelog says/debugnow toggles debug logging on mid-session and debug logs are no longer written by default. It also reports that the CLI reference does not explain the distinction betweenclaude --debugat startup and/debugduring an active session.---
Verification Results
Claim 1: The
/debugdocumentation should say that debug logging is off by default and that/debugenables logging mid-sessionStatus: RESOLVED
At https://code.claude.com/docs/en/changelog, line 593: "Updated
/debugto toggle debug logging on mid-session, since debug logs are no longer written by default".At https://code.claude.com/docs/en/slash-commands, line 29: "Enable debug logging for the current session and troubleshoot issues by reading the session debug log. Debug logging is off by default unless you started with
claude --debug, so running/debugmid-session starts capturing logs from that point forward."At https://code.claude.com/docs/en/env-vars, line 61: "Requires debug mode to be enabled separately via
--debugor/debug: setting this variable alone does not enable logging."Verdict: The current
/debugdocumentation now explicitly says that logs are off by default and that running/debugmid-session starts capturing logs, so the primary stale-description problem reported in the issue has been corrected.---
Claim 2: The CLI reference should distinguish startup debug logging from the mid-session
/debugcommandStatus: UNRESOLVED
At https://code.claude.com/docs/en/cli-reference, line 53: "
--debugenables debug mode with optional category filtering (for example,\"api,hooks\"or\"!statsig,!file\")."At https://code.claude.com/docs/en/cli-reference, line 54: "
--debug-file <path>writes debug logs to a specific file path and implicitly enables debug mode."These entries do not mention
/debugand do not explain the startup-versus-mid-session distinction.Verdict: The CLI reference still lacks the cross-reference and behavioral distinction requested in the issue.
---
Current State
| Claim | Status |
|-------|--------|
|
/debugdocumentation says logs are off by default and that/debugenables logging mid-session | RESOLVED || The CLI reference distinguishes
claude --debugfrom/debugand cross-references the mid-session command | UNRESOLVED |---
Suggested Fix
Update https://code.claude.com/docs/en/cli-reference so the
--debugentry explains that it enables logging from session startup and points readers to/debugfor enabling logging after a session has already started.---
References
/debugtoggles debug logging on mid-session and that debug logs are no longer written by default/debugentry stating that debug logging is off by default and that running/debugmid-session starts capturing logs--debugor/debug--debugand--debug-fileentries, which do not mention/debugor explain the startup-versus-mid-session distinction---
Conclusion & Recommendation
Primary Concern: The issue asked the docs to reflect that
/debugenables debug logging mid-session whileclaude --debugenables it from session startup.Resolution Status: UNRESOLVED
Recommendation: KEEP OPEN
The main
/debugdescription has been corrected, but the CLI reference still does not cross-reference/debugor explain the distinction between startup and mid-session debug logging.---
Issue #31680 Verification
| Field | Value |
|-------|-------|
| Title | [DOCS] /debug command docs outdated — does not reflect mid-session toggle behavior |
| Issue Date | 2025-07-10 (approximate, from changelog v2.1.71 reference) |
| Verification Date | 2026-04-27 |
| Status | RESOLVED |
Issue Summary
The issue reported that the
/debugslash command documentation was outdated after the v2.1.71 changelog changed/debugfrom a "read the debug log" command to a mid-session toggle that enables debug logging. Two specific behavior changes needed documenting: (1) debug logs are off by default, and (2)/debugtoggles logging on for the current session. Two pages were flagged:slash-commands.md(stale description) andcli-reference.md(missing cross-reference).Verification Results
Claim 1:
slash-commands.mdcontains stale/debugdescriptionslash-commands.mdpage (now titled "Extend Claude with skills") no longer contains a standalone/debugdescription. Line 14 redirects to the commands reference: "For built-in commands like/helpand/compact, and bundled skills like/debugand/simplify, see the commands reference." Line 23 lists/debugas a bundled skill with no detailed description. The old text ("troubleshoots your current Claude Code session by reading the session debug log") has been removed entirely.Claim 2:
commands.mddoes not document mid-session toggle behaviorcommands.mdline 36 now reads: "Skill. Enable debug logging for the current session and troubleshoot issues by reading the session debug log. Debug logging is off by default unless you started withclaude --debug, so running/debugmid-session starts capturing logs from that point forward. Optionally describe the issue to focus the analysis." This covers both behavior changes: default-off logging and the mid-session toggle.Claim 3:
cli-reference.mdlacks cross-reference from--debugto/debugslash commandcli-reference.mdlines 56-57 document--debugand--debug-filebut do not include an explicit cross-reference to the/debugslash command. However, thecommands.mdentry for/debugmentionsclaude --debugas the startup alternative, providing the link in the reverse direction. Theenv-vars.md,hooks-guide.md, andclaude-directory.mdall cross-reference--debugand/debugtogether, reducing the practical impact of this gap.cli-reference.mdcould still be added, but users following the docs will find the information.Current State
| Page | Issue Claim | Current State |
|------|-------------|---------------|
|
slash-commands.md| Stale/debugdescription | Redirects to commands reference; old text removed ||
commands.md| Missing toggle behavior | Updated with full mid-session toggle description ||
features-overview.md| Lists/debugwithout behavior details | Lists as bundled skill; links to commands reference ||
cli-reference.md| No cross-reference to/debugslash command | Still lacks explicit cross-reference (minor gap) |Suggested Fix
N/A — primary concern resolved. A future improvement could add a brief note in
cli-reference.md's--debugentry linking to the/debugslash command, but this is low priority.References
Conclusion & Recommendation
/debugdescription that did not reflect the mid-session toggle behavior has been resolved.slash-commands.mdandcommands.mdnow accurately describe the current/debugbehavior.cli-reference.mdcross-reference gap is minor and does not impede user understanding.This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.