From a57687d10c1790973797bce1232e0f5d27274838 Mon Sep 17 00:00:00 2001
From: Matt Bruce <mbrucedogs@gmail.com>
Date: Fri, 1 Aug 2025 08:03:43 -0500
Subject: [PATCH] Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>

---
 PRD.md    | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  7 +++++++
 2 files changed, 61 insertions(+)

diff --git a/PRD.md b/PRD.md
index 3e12cdf..de6f5c1 100644
--- a/PRD.md
+++ b/PRD.md
@@ -244,6 +244,14 @@ src/
 - **Purpose**: Keeps root directory clean and organizes test code properly
 - **Import Path**: Tests can import from parent modules using relative imports
 
+### Using Tests for Issue Resolution
+- **FIRST STEP**: When encountering issues, check `src/tests/` directory for existing test files
+- **EXISTING TESTS**: Many common issues already have test cases that can help debug problems
+- **DEBUG SCRIPTS**: Look for `debug_*.py` files that may contain troubleshooting code
+- **SPECIFIC TESTS**: Search for test files related to the specific functionality having issues
+- **EXAMPLES**: Test files often contain working examples of how to use the functionality
+- **PATTERNS**: Existing tests show the correct patterns for database queries, API calls, and data processing
+
 ## Server Setup Requirements
 
 ### MusicBrainz Server Configuration
@@ -507,6 +515,52 @@ docker-compose run --rm musicbrainz-cleaner python3 -m src.cli.main --test-conne
 - User feedback integration
 - Database connection troubleshooting guide
 - **NEW**: Collaboration detection troubleshooting guide
+- **NEW**: Test-based troubleshooting guide
+
+### Troubleshooting with Tests
+When encountering issues, the `src/tests/` directory contains valuable resources:
+
+#### **Step 1: Check for Existing Test Cases**
+```bash
+# List all available test files
+ls src/tests/
+
+# Look for specific functionality tests
+ls src/tests/ | grep -i "collaboration"
+ls src/tests/ | grep -i "artist"
+ls src/tests/ | grep -i "database"
+```
+
+#### **Step 2: Run Relevant Debug Scripts**
+```bash
+# Run debug scripts for specific issues
+python3 src/tests/debug_artist_search.py
+python3 src/tests/test_collaboration_debug.py
+python3 src/tests/test_failed_collaborations.py
+```
+
+#### **Step 3: Use Test Files as Examples**
+- **Database Issues**: Check `test_simple_query.py` for database connection patterns
+- **Artist Search Issues**: Check `debug_artist_search.py` for search examples
+- **Collaboration Issues**: Check `test_failed_collaborations.py` for collaboration handling
+- **Title Cleaning Issues**: Check `test_title_cleaning.py` for title processing examples
+
+#### **Step 4: Common Test Files by Issue Type**
+| Issue Type | Relevant Test Files |
+|------------|-------------------|
+| Database Connection | `test_simple_query.py`, `test_cli.py` |
+| Artist Search | `debug_artist_search.py`, `test_100_random.py` |
+| Collaboration Detection | `test_failed_collaborations.py`, `test_collaboration_debug.py` |
+| Title Processing | `test_title_cleaning.py` |
+| CLI Issues | `test_cli.py`, `quick_test_20.py` |
+| General Debugging | `debug_artist_search.py`, `test_100_random.py` |
+
+#### **Step 5: Extract Working Code**
+Test files often contain working code snippets that can be adapted:
+- Database connection patterns
+- API call examples
+- Data processing logic
+- Error handling approaches
 
 ## Lessons Learned
 
diff --git a/README.md b/README.md
index 3f039eb..1d90f6a 100644
--- a/README.md
+++ b/README.md
@@ -638,6 +638,13 @@ Using database connection
 - **NEW**: Verify the collaboration pattern is supported (ft., feat., featuring, &, and, ,)
 - **NEW**: Check case sensitivity - patterns are case-insensitive
 
+### Using Tests for Troubleshooting
+- **FIRST STEP**: Check `src/tests/` directory for existing test files that might help
+- **DEBUG SCRIPTS**: Run `python3 src/tests/debug_artist_search.py` for artist search issues
+- **COLLABORATION ISSUES**: Check `src/tests/test_failed_collaborations.py` for collaboration examples
+- **DATABASE ISSUES**: Look at `src/tests/test_simple_query.py` for database connection patterns
+- **WORKING EXAMPLES**: Test files often contain working code that can be adapted for your issue
+
 ## 🎯 Use Cases
 
 - **Karaoke Systems**: Clean up song metadata for better search and organization