diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..b8cc378
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,46 @@
+# Troubleshooting: Reviewer Did Not Run
+
+## Quick Checklist
+
+Before diving deeper, verify the basics:
+
+- The workflow file exists at `.gitea/workflows/kodo-reviewer.yaml`
+- Secrets `CC_GITEATOKEN` and `CC_API_KEY` are set in repository settings
+- The runner `kodo-review` is online and available
+- The PR title does **not** contain `[no ai]`
+- The event that triggered the workflow matches one of the configured triggers
+
+---
+
+## Common Causes & Fixes
+
+### 1. Secrets are missing or misconfigured
+
+If `CC_GITEATOKEN` or `CC_API_KEY` are not set, the action will fail silently or error out.
+
+**How to check:**
+1. Go to repository **Settings → Secrets**
+2. Verify both secrets exist:
+   - `CC_GITEATOKEN` — Gitea token with read/write access to PRs
+   - `CC_API_KEY` — Anthropic API key
+
+**Fix:** Add/regenerate missing secrets or contact with `devops` team.
+
+---
+
+### 2. PR title contains `[no ai]`
+
+The action checks for `[no ai]` in the PR title and skips execution if found.
+
+**Fix:** Remove `[no ai]` from the PR title and push a new commit or re-open the PR.
+
+---
+
+## Still Not Working?
+
+Provide the following information when asking for help from `devops` team:
+
+- Runner name and status (`kodo-review`)
+- Workflow run URL
+- Event that was expected to trigger the review
+- Observed and expected behavior