docs(go): add go fallback strategy troubleshooting guide

docs/detectors/go.md

@@ -2,36 +2,45 @@
 
 ## Requirements
 
-Go detection depends on the following to successfully run:
+Go detection runs when one of the following files is found in the project:
 
-- `go.mod` or `go.sum` files
+- `go.mod` or `go.sum`
 
 ## Default Detection strategy
 
-Go detection depends on the following to successfully run:
+Default Go detection depends on the following to successfully run:
 
 - Go v1.11+.
 
 Full dependency graph generation is supported if Go v1.11+ is present
 on the build agent. If no Go v1.11+ is present, fallback detection
 strategy is performed.
 
-Go detection is performed by parsing output from executing [go list -m
--json all](1). To generate the graph, the command [go mod graph](2) is
-executed, this only adds edges between the components that were
-already registered by `go list`.
+Go detection is performed by parsing output from executing 
+[go list -mod=readonly -m -json all](1). To generate the graph, the command 
+[go mod graph](2) is executed. This only adds edges between the components 
+that were already registered by `go list`.
 
 ## Fallback Detection strategy
 
+The fallback detections trategy is known to overreport (see the 
+[known limitations](#known-limitations)). Read through the 
+[troubleshooting section](#troubleshooting-failures-to-run-the-default-go-detection-strategy)
+for tips on how to ensure that the newer, more accurate default 
+detection strategy runs successfully. 
+
+To force the fallback detection strategy, set the environment 
+variable: `DisableGoCliScan=true`
+
 ### `go.mod` before go 1.17
 
 Go detection is performed by parsing any `go.mod` or `go.sum` found
 under the scan directory.
 
-Only root dependency information is generated instead of full graph.
-I.e. tags the top level component or explicit dependency a given
-transitive dependency was brought by. Given a dependency tree A -> B
--> C, C's root dependency is A.
+Only root dependency information is generated in the fallback detection 
+strategy. The full graph is not detected. Given a dependency tree `A->B->C`, 
+only `A`, `C`'s root dependency, is detected.
+
 
 ### `go.mod` after 1.17
 
@@ -41,8 +50,70 @@ dependencies, including transitive ones. [^3]
 
 Similarly, no graph is generated.
 
-**To force fallback detection strategy, create set environment
-variable `DisableGoCliScan=true`.**
+## Troubleshooting failures to run the default Go detection strategy
+The fallback detection strategy is known to overreport by nature of 
+parsing `go.sum` files which contain historical component information. 
+
+If you are experiencing overdetection from `go.sum` files or have
+otherwise been made aware that you are using the fallback Go detection 
+strategy, search Component Detection output for the following to determine 
+what action is needed: 
+
+| CD output                                     | Solution                                                               |
+| --------------------------------------------- | ---------------------------------------------------------------------- |
+| `Go CLI was not found in the system`           | [Ensure that Go v1.17+ is installed](#ensure-that-go-v117-is-installed-on-the-build-agent) |
+| `#[error]Go CLI command "go list -m -json all" failed with error:` | [Resolve `go list` errors](#resolve-go-list-errors)                   |
+| `Go cli scan was manually disabled, fallback strategy performed.` | [Remove the `DisableGoCliScan` environment variable](#remove-the-disablegocliscan-environment-variable) |
+| _Timeouts in Go detection_                     | [Fetch Go modules](#fetch-go-modules-before-the-component-detection-build-task-runs) |
+
+
+If you do not believe that Go is used in your project but Go detection is running, 
+it is likely that you need to [clean up extraneous build files](#clean-up-extraneous-build-files).
+
+### Ensure that Go v1.17+ is installed on the build agent
+Install Go CLI tools v1.17+ and ensure that it is available at the 
+Component Detection step. 
+
+If Go CLI tools are installed in a prior build step but 
+Component Detection is not finding them, ensure that they 
+are not cleaned up or installed inside a container.  
+
+### Resolve `go list` errors. 
+
+Errors are logged in the Component Detection build task output and begin with 
+`#[error]Go CLI command "go list -m -json all" failed with error:`. These errors 
+are typically caused by version resolution problems or incorrectly formatted `go.mod` 
+files. 
+
+### Remove the `DisableGoCliScan` environment variable
+The variable should not be set or should be set to `false`.
+
+### Fetch Go modules before the Component Detection build task runs. 
+If modules are not fetched, `go list` will pull the modules and may 
+negatively impact performance at detection time.  
+
+If you are still experiencing timouts, the fallback strategy might be more 
+appropriate for your project:  
+1. Set `DisableGoCli=true`.
+1. Run `go mod tidy` to clean your `go.mod` and `go.sum`s to reduce overreporting.
+1. Install Go v1.17+ to bypass go.sum scanning.
+
+### Clean up extraneous build files
+Go detection runs when a `go.sum` or `go.mod` file is encountered. If 
+you do not use Go in your project, search for the following in Component 
+Detection build output to find the paths to the Go files CD has detected. 
+Component Detection must be running in debug mode to see these logs:  
+
+`##[debug]Found Go.mod:` or   
+`##[debug]Found Go.sum:`
+
+When you have found the affected files, you may: 
+1. Delete the files if they exist but are not necessary in your project.
+2. Add a clean-up step to your build to remove the files if they are 
+generated prior to the Component Detection build step but are not related 
+to your project. 
+3. [Exclude the directory](../detector-arguments.md) if it should not be scanned by Component 
+Detection.
 
 ## Known limitations
 
@@ -69,9 +140,8 @@ directive](https://go.dev/doc/modules/gomod-ref#exclude).
 
 ## Environment Variables
 
-If the environment variable `DisableGoCliScan` is set to `true`, the
-Go detector parses `go.mod` and `go.sum` to discover dependencies.
-otherwise, it executes default strategy.
+If the environment variable `DisableGoCliScan` is set to `true`, the 
+Go detector forcibly executes the [fallback strategy](#fallback-detection-strategy).
 
 ## Go Overview