docs: debugging additions

[royendo]

INSERT DESCRIPTION HERE

Checklist:

• Covered by tests
• Ran it and it works as intended
• Reviewed the diff before requesting a review
• Checked for unhandled edge cases
• Linked the issues it closes
• Checked if the docs need to be updated. If so, create a separate Linear DOCS issue
• Intend to cherry-pick into the release branch
• I'm proud of this work!

[ericpgreen2]

Code Review: docs: debugging additions

Thanks for putting together this comprehensive debugging guide! This is a great improvement that consolidates troubleshooting information into a single source of truth. A few suggestions:

Structure Issues

1. Remove the "Debugging Tools" header

The "Debugging Tools" section with its bullet list reads like a table of contents, but it's at the same heading level (H2) as the sections it references. This creates an awkward hierarchy. I'd suggest removing the ## Debugging Tools header entirely and letting the intro paragraph flow directly into the content—the sidebar already provides navigation.

2. Duplicate H3 headers

### Common Log Fields

### Generic Logging

"Common Log Fields" has no content before "Generic Logging" starts. Either remove "Common Log Fields" or add introductory content between them.

Content Suggestions

3. Flesh out "Advanced Debugging Techniques"

This section is fairly brief—it covers the flags and links to Trace Viewer but could benefit from:

• Explaining the difference between --debug and --verbose
• Mentioning rill project logs for cloud debugging
• Any other useful debugging flags or techniques

4. Consider adding a note about log levels

The examples show INFO and WARN but don't explain what determines log levels or whether there are others (DEBUG, ERROR, etc.).

Minor Item

5. Fix trace-viewer.md description (separate PR is fine)

The existing trace-viewer.md has description: "Alter dashboard look and feel" which appears to be a copy-paste error. Should be something like "Visualize resource reconciliation and trace execution".

---

Overall this is a solid addition to the docs. Nice work consolidating the debugging information!

Developed in collaboration with Claude Code and Eric.

[ericpgreen2]

Generally looks good. Approving with comments.