From ab43f7264a05f694f4a7b1f4a09f8add972381ab Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Fri, 9 Jan 2026 22:07:33 +0000
Subject: docs: track production sync issues in work/active-issues/

- Update production-sync-testing.md to document issues as individual markdown files in work/active-issues/ instead of polluting the tracked how-to guide
- Add issue template and workflow for creating, viewing, and resolving issues
- Document active-issues/ purpose in work/README.md
- Prevents accidental commits of transient testing issues
- Makes issue management cleaner and more focused
---
 docs/how-to/production-sync-testing.md | 88 +++++++++++++++++++++++++++++-----
 1 file changed, 75 insertions(+), 13 deletions(-)

(limited to 'docs/how-to/production-sync-testing.md')

diff --git a/docs/how-to/production-sync-testing.md b/docs/how-to/production-sync-testing.md
index a55e9ea..b0f93b0 100644
--- a/docs/how-to/production-sync-testing.md
+++ b/docs/how-to/production-sync-testing.md
@@ -1,5 +1,7 @@
 # How-To: Test Sync Against Production Data
 
+> **Quick Start Prompt:** Run a 30-second production sync test following docs/how-to/production-sync-testing.md. Use the minimal test command with sanitized output. Analyze the log for errors, warnings, and unexpected patterns. Document findings as individual markdown files in work/active-issues/ and suggest code fixes or logging improvements.
+
 **Problem:** Debug and improve sync behavior using real-world data from production relays  
 **Difficulty:** Intermediate  
 **Time:** 30 minutes per iteration
@@ -169,7 +171,43 @@ grep -i panic iteration-1.log
 
 ### Step 3: Document Findings
 
-Add findings to this file's [Known Issues](#known-issues) section or create GitHub issues.
+Create individual markdown files in `work/active-issues/` for each issue discovered:
+
+```bash
+# Example: Document a connection timeout issue
+cat > work/active-issues/connection-timeout-bootstrap.md <<'EOF'
+# Issue: Connection Timeout on Bootstrap Relay
+
+**Discovered:** 2026-01-09
+**Status:** Open
+
+## Symptoms
+
+- Connection to wss://git.shakespeare.diy fails after 10s timeout
+- Log shows: `error: connection failed: timeout`
+- Occurs 100% of time with this relay
+
+## Root Cause
+
+[To be determined]
+
+## Proposed Fix
+
+- Increase connection timeout from 10s to 30s for initial bootstrap
+- Add retry logic with exponential backoff
+- Consider fallback bootstrap relays
+
+## Code Location
+
+- `src/sync/relay_connection.rs:45` - connection timeout constant
+EOF
+```
+
+**Why individual files?**
+- Keeps the how-to guide clean and focused
+- Prevents accidental commits of transient issues to tracked files
+- Easy to delete resolved issues or archive important ones
+- Each file can be worked on independently
 
 ### Step 4: Fix and Re-test
 
@@ -215,26 +253,50 @@ If a log line appears too frequently:
 tracing::trace!("Per-event detail that's too noisy");
 ```
 
-## Known Issues
+## Active Issues
 
-*Document issues discovered during testing here. Delete this section when empty.*
+Issues discovered during production sync testing are tracked in `work/active-issues/` as individual markdown files.
 
-### Template for New Issues
+**View current issues:**
+```bash
+ls work/active-issues/
+```
 
-```markdown
-### Issue: [Short description]
+**Create a new issue:**
+```bash
+# Use kebab-case filename describing the issue
+cat > work/active-issues/[issue-name].md <<'EOF'
+# Issue: [Short Description]
 
 **Discovered:** [Date]
-**Status:** [Open/Fixed in PR#xxx]
+**Status:** Open
+
+## Symptoms
+
+- Log patterns observed
+- Reproduction steps if known
 
-**Symptoms:**
-- Log pattern observed
+## Root Cause
 
-**Root cause:**
-- [If known]
+[To be determined / Known cause]
 
-**Fix:**
-- [If known]
+## Proposed Fix
+
+- Suggested code changes
+- Alternative approaches
+
+## Code Location
+
+- File paths and line numbers where changes are needed
+EOF
+```
+
+**Resolve an issue:**
+```bash
+# After fixing, either delete or move to archive
+rm work/active-issues/resolved-issue.md
+# OR
+mv work/active-issues/important-issue.md docs/archive/2026-01-09-important-issue.md
 ```
 
 ---
-- 
cgit v1.2.3