[AkashGoswamy]

Closes #12

What does this change?

Adds TROUBLESHOOTING.md at the repo root, compiling the six known gotchas from the issue into one discoverable file. Each entry follows symptom → cause → what to do, with links back to the source examples. Also adds one line linking to it from the "Learn More" section of README.md.

Why?

The gotchas currently sit in separate examples/*/RESULTS.md files, so users hitting them are unlikely to find them. This is the documentation-only task requested in #12. I read CONTRIBUTING.md and the RESULTS.md files from the examples before writing, so each entry reflects what was observed in a real run.

Checklist

• I ran the full test suite locally (pytest -v) and it passes. — N/A, documentation only, no code changed
• I added a new test that fails without this change and passes with it. — N/A, documentation only
• This does not modify any existing test's behavior/assertions, unless that's the explicit point of this PR (explain above if so). — No tests touched
• If this changes public behavior, I added a CHANGELOG.md entry following the existing format. — N/A, no behavior change
• If this is a bug fix, I can point to how I reproduced the original bug (a script, an issue, a failing test). — N/A, not a bug fix

Anything else worth knowing?

Entry 1 says "as of v0.5.3" because I found no release note showing check() now surfaces exceptions. If that behavior has changed on main, I'm happy to update the entry.

[Vedantgitbot]

@AkashGoswamy , This is great, thanks. Exactly the format I wanted, and the extra "rule of thumb" notes are a nice touch.

One fix before merging: link "the Anthropic example" in entry 6, like the others (examples/opencode13241-eng_anthropic).

Also, entry 1 is correctly worded as-is, v0.5.3 fixed a related on_attempt bug, but the core issue (exceptions looking like UNCERTAIN) is still open. Good that you kept that distinction accurate.

Merging once the link's added.