From 72f2550a22212f5d51fd4dce538ce643a434c98b Mon Sep 17 00:00:00 2001
From: Jon Fairbanks <fairplay89@gmail.com>
Date: Wed, 8 May 2024 16:53:32 -0700
Subject: [PATCH] Add Troubleshooting Docs

---
 .github/ISSUE_TEMPLATE/bug_report.md | 21 +++++++++++++--------
 README.md                            |  5 +++--
 docs/troubleshooting.md              | 28 ++++++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 10 deletions(-)
 create mode 100644 docs/troubleshooting.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 796a0f7..312f997 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -7,17 +7,22 @@ assignees: ''
 
 ---
 
-**Describe the bug**
+**Describe the Bug**
 A clear and concise description of what the bug is.
 
-**To Reproduce**
+**Troubleshooting**
+I have read the Local RAG [troubleshooting guide](../../docs/troubleshooting.md), reviewed my application state and log file:
+- [ ] Yes
+- [ ] No
+
+**How To Reproduce**
 Steps to reproduce the behavior:
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
-**Expected behavior**
+**Expected Behavior**
 A clear and concise description of what you expected to happen.
 
 **Screenshots**
@@ -28,14 +33,14 @@ If applicable, attach log files to help explain your problem. **Reproducing your
 
 **Desktop (please complete the following information):**
  - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
+ - Browser [e.g. Chrome, Safari]
  - Version [e.g. 22]
 
 **Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
+ - Device: [e.g. iPhone 15]
+ - OS: [e.g. iOS 17.x]
+ - Browser [e.g. Stock Browser, Safari]
  - Version [e.g. 22]
 
-**Additional context**
+**Additional Context**
 Add any other context about the problem here.
diff --git a/README.md b/README.md
index 5857e61..c086621 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,8 @@
 ![local-rag-demo](demo.gif)
 
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8588/badge)](https://www.bestpractices.dev/projects/8588)
-![GitHub commit activity](https://img.shields.io/github/commit-activity/t/jonfairbanks/local-rag)
-![GitHub last commit](https://img.shields.io/github/last-commit/jonfairbanks/local-rag)
+![GitHub Commit Activity](https://img.shields.io/github/commit-activity/t/jonfairbanks/local-rag)
+![GitHub Last Commit](https://img.shields.io/github/last-commit/jonfairbanks/local-rag)
 ![GitHub License](https://img.shields.io/github/license/jonfairbanks/local-rag)
 
 Offline, Open-Source RAG
@@ -28,6 +28,7 @@ Learn More:
 - [Using Local RAG](docs/usage.md)
 - [RAG Pipeline](docs/pipeline.md)
 - [Planned Features](docs/todo.md)
+- [Troubleshooting](docs/troubleshooting.md)
 - [Known Bugs & Issues](docs/todo.md#known-issues--bugs)
 - [Resources](docs/resources.md)
 - [Contributing](docs/contributing.md)
\ No newline at end of file
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..cf151e1
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,28 @@
+# Troubleshooting
+
+In the event that an error occurs when using Local RAG, checking out the current application state and logfile can provide insights into what is happening behind the scenes.
+
+Note: To better understand what is happening under the hood and aid in troubleshooting, checkout the [Pipeline documentation](pipeline.md) as well.
+
+## Application State
+
+Each stage of the RAG pipeline stores its data in the application state. 
+
+In order for a successful RAG conversation to take place the following state values must NOT be null:
+- `documents` - if null, there was an error processing your documents
+- `llm` - if null, there was an error creating the Ollama LLM instance
+- `query_engine` - if null, errors occurred when creating embeddings for your your documents
+
+To view the current application state:
+- Navigate to the Settings panel
+- Toggle the Advanced Options slider
+- State is now visible at the bottom of Settings
+- Verify that the above state values are valid
+
+## Log File
+
+By default, Local RAG will create a `local-rag.log` file in the root application folder.
+
+Each step of the RAG process is logged into this file whether the required step was successful or encountered an error. 
+
+Reviewing this log can give you insights into what took place when processing your documents.
\ No newline at end of file