A useful troubleshooting record says more than “it worked in the end.” It helps the next investigation reach the cause faster.
Record template
- Symptom: what actually appeared, including the original error text.
- Expected state: what should have happened.
- Scope: which page, device, version, or step is affected.
- Hypotheses: possible causes, clearly marked as unverified.
- Evidence: what each check supports or rules out.
- Fix: the smallest change connected to the cause.
- Regression check: repeat the original path and inspect nearby behavior.
An example from this project
The knowledge base initially showed a large blank area on mobile. The build passed, but a visual capture showed delayed content. Inspection found that an unused math plugin loaded a remote stylesheet and blocked the first render. Disabling that plugin removed the remote dependency and restored the mobile first screen.
Related: Building the Black Cat Knowledge Base.