TROUBLESHOOTING.md in platformos-check-0.4.12 vs TROUBLESHOOTING.md in platformos-check-0.4.13

@@ -1,35 +1,44 @@
 # Troubleshooting
 
 ## Issues with Language Server
 
-### Language server erroring out on startup
+### Language Server Crashing on Startup
 
-The following error can cause language server to crash:
+The following error can cause Language Server to crash:
+
+**Error Message:**
 ```bash
 Calling `DidYouMean::SPELL_CHECKERS.merge!(error_name => spell_checker)' has been deprecated. Please call `DidYouMean.correct_error(error_name, spell_checker)' instead.
 /Users/johndoe/.gem/ruby/3.1.2/gems/bundler-2.2.22/lib/bundler/spec_set.rb:91:in `block in materialize': Could not find ruby-prof-0.18.0 in any of the sources (Bundler::GemNotFound)
 ```
 
-Confirm the version of platformos-check matches the version in the wrapper in `~/bin/platformos-check-language-server`. If it doesn't match the ruby version, run the following from the platformos-check directory:
+**Solution:**
+Ensure the `platformos-check` version in the wrapper in `~/bin/platformos-check-language-server` matches the expected Ruby version. If it doesn't match the Ruby version, run the following command from the platformos-check directory:
 
 ```bash
-chruby 3.1.2 #your `~/bin/platformos-check-language-server` ruby version
+chruby 3.1.2  #your `~/bin/platformos-check-language-server` ruby version
 bundle install
 ```
 
-### Language server sends an `initialize()` request to the client and stops
+If discrepancies are found, update your environment with the correct version of Ruby and re-install the necessary gems:
 
-To debug, confirm these steps are included in your local language server startup script:
+### Language Server Initialization Issue
 
+**Symptom:**
+
+The language server sends an `initialize()` request to the client but then stops responding.
+
+**Debugging Steps:**
+
+1. Ensure your local language server startup script includes these steps:
 ```bash
 export PLATFORMOS_CHECK_DEBUG=true
 export PLATFORMOS_CHECK_DEBUG_LOG_FILE="/tmp/platformos-check-debug.log"
 touch "$PLATFORMOS_CHECK_DEBUG_LOG_FILE"
 ```
 
-An example script can be found [here](/CONTRIBUTING.md#run-language-server).
+An example script can be found [in the Contributing Guide](/CONTRIBUTING.md#run-language-server).
 
-Open `/tmp/platformos-check-debug.log` in your IDE. Check if there are any exceptions being raised by language server.
+2. Open the debug log located at `/tmp/platformos-check-debug.log` in your IDE. Check if there are any exceptions being raised by the language server.
 
-If there are no exceptions, check if there are any logs that aren't in jsonrpc. The language server and client use stdin and stdout to communicate using jsonrpc. Debugging statements that aren't in a jsonrpc format might trigger unexpected behavior (this includes any logs from language server or echo statements in your language server script).
-
+3. If no exceptions are found, verify that all logs are properly formatted in JSON-RPC. The language server and client communicate using JSON-RPC over `stdin` and `stdout`. Debugging statements that aren't in a JSON-RPC format might trigger unexpected behavior. This includes any logs from the language server or echo statements in your language server script.