troubleshootinglisted

# Troubleshooting Noctra Use this runbook when Noctra behaves unexpectedly. Prefer `noctra doctor`, service logs, and per-ticket agent logs before changing code. ## First Checks 1. Run `noctra doctor` from the same host and config context as the service. 2. Check the startup banner in service logs; it prints the resolved backend, trigger mode, states or label, repo routing, review gate, auto-iterate, and notifications. 3. Inspect the per-ticket transcript under the configured log directory: ```bash make tail TICKET=ENG-42 # or tail -f logs/ENG-42.log ``` Config defaults to `~/.noctra/` for `.env` and `logs/`, but a checkout containing `.env`, `.env.example`, or `go.mod` uses the current directory. ## Tickets Are Not Picked Up Check the trigger mode first: ```env TRIGGER_MODE=state TRIGGER_STATE=Next IN_REVIEW_STATE=In Review ``` or: ```env TRIGGER_MODE=label TRIGGER_LABEL=noctra IN_REVIEW_STATE=In Review ``` Then verify: 1. `LINEAR_TEAM_KEY` matches the ticket prefix, such as `ENG` for `ENG-42`. 2. State and label names match Linear exactly; names are case-sensitive. 3. The Linear API key has workspace access to read issues and write comments/state changes. 4. The ticket's Linear project has a `Repo:` directive in its description, or `REPO_PATH` is set as a fallback. Query Linear states directly when names are unclear: ```bash curl -s -X POST \ -H "Content-Type: application/json" \ -H "Authorization: $LINEAR_API_KEY" \ --data '{"query":"{ team(key: \"ENG\"