From abc5498f60bafc65c3781ce419e337374e2e7bc2 Mon Sep 17 00:00:00 2001 From: root Date: Tue, 24 Feb 2026 21:43:57 -0600 Subject: [PATCH] docs: Add Known Issues section to checklist Document all issues discovered during TrueRecall v2 deployment: - Gem quality issues (malformed fields, duplicates, 4b vs 30b) - OpenClaw UI glitches during compaction - v1 migration conflicts and detection - Security issues (IPs, paths, backup files) - Multi-remote git configuration - Model-specific issues - Pre-release checklist for future deployments --- checklist.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) diff --git a/checklist.md b/checklist.md index 5eca5af..02b5df5 100644 --- a/checklist.md +++ b/checklist.md @@ -455,7 +455,88 @@ openclaw config get plugins.entries.memory-qdrant ./push-all.sh ``` -### 11.2 Sign-off Checklist +--- + +## 12. Known Issues & Solutions (Discovered During Deployment) + +### 12.1 Gem Quality Issues + +| Issue | Cause | Solution | Status | +|-------|-------|----------|--------| +| **Malformed importance** | Model outputs `3` instead of `"high"` | Strengthen prompt: "MUST be string, NEVER 1/2/3" | ✅ Fixed in curator-prompt.md | +| **Malformed confidence** | Model outputs `"0.7"` instead of `0.7` | Strengthen prompt: "MUST be float, NEVER integers" | ✅ Fixed in curator-prompt.md | +| **"User confirmed..." pattern** | Model wraps insights in passive voice | Add rule: "NEVER start with 'User confirmed/asked/said'" | ✅ Fixed in curator-prompt.md | +| **Duplicate gems** | Same decisions extracted multiple times | Add deduplication check (similarity >0.85 = skip) | ✅ Documented in README | +| **Low-quality 4b gems** | 4b model lacks nuance | Use 30b curator for production | ✅ Documented in README | + +**Prevention:** See Section 6.3 (Duplication Check) and curator-prompt.md "Critical Validation Rules" + +### 12.2 OpenClaw UI Issues + +| Issue | Cause | Workaround | Status | +|-------|-------|------------|--------| +| **Text invisible after compaction** | WebSocket sync during history replacement | Wait 2-3s or hard refresh (Ctrl+Shift+R) | ⚠️ Known limitation | +| **Messages out of order** | UI state gets briefly desynced | Hard refresh if stuck | ⚠️ Known limitation | + +**Note:** These are OpenClaw Control UI limitations, not fixable from TrueRecall side. + +### 12.3 v1 Migration Issues + +| Issue | Cause | Solution | Status | +|-------|-------|----------|--------| +| **v1 conflicts** | Both v1 and v2 running simultaneously | Remove v1 completely before installing v2 | ✅ Installer detects v1 and warns | +| **Duplicate cron jobs** | v1 curator still running | Remove v1 cron entries | ✅ Documented in installer | +| **Collection naming** | v1 uses `memories`, v2 uses `memories_tr` | Collections are separate, no data conflict | ✅ By design | + +**Prevention:** Installer now detects v1 and requires acknowledgment before proceeding. + +### 12.4 Repository & Security Issues + +| Issue | Cause | Solution | Status | +|-------|-------|----------|--------| +| **Private IPs in code** | Hardcoded 10.0.0.x addresses | Replace with placeholders (``, etc.) | ✅ Fixed in main_projects | +| **Absolute paths** | `/root/`, `/home/n8n/` in docs | Replace with `~/` or placeholders | ✅ Fixed in main_projects | +| **Backup files committed** | `*.bak`, `*.neuralstream.bak` | Removed + added `.gitignore` | ✅ Fixed | +| **Session notes in repo** | `session.md` with timestamps | Removed from git, kept local | ✅ Fixed | +| **Debug files committed** | `debug_curator.py`, `test_*.py` | Removed + `.gitignore` | ✅ Fixed | +| **Repo visibility** | Initially set to private (should have asked) | Changed to public for sharing | ✅ Fixed | + +**Prevention:** See Section 7 (Security & Privacy Review) and `.gitignore` + +### 12.5 Multi-Remote Git Issues + +| Issue | Cause | Solution | Status | +|-------|-------|----------|--------| +| **GitHub blocked** | Account issues | Skip GitHub in push-all.sh | ✅ Configured | +| **Token in remote URL** | Security risk | Remove after push, use credential helper | ✅ Fixed | +| **Remote naming** | `origin` vs `github` | Renamed to `github` for clarity | ✅ Fixed | + +### 12.6 Model-Specific Issues + +| Issue | Cause | Solution | Status | +|-------|-------|----------|--------| +| **4b JSON reliability** | Smaller model struggles with JSON output | Add JSON fallback/parsing retry | ✅ Documented | +| **30b speed** | 30b slower than 4b | Acceptable for quality (~3s vs ~10s) | ✅ Documented | +| **Embedding model choice** | `snowflake` vs `mxbai` | `mxbai` = higher accuracy, `snowflake` = faster | ✅ Documented | + +### 12.7 Checklist for Future Deployments + +Before releasing/sharing: + +- [ ] Run all commands in Section 7.1 (Security Checks) +- [ ] Verify no `*.bak` files exist: `find . -name "*.bak"` +- [ ] Verify no `__pycache__` committed +- [ ] Verify no session-specific timestamps in markdown +- [ ] Verify no debug/test files in repo +- [ ] Check `.gitignore` is comprehensive +- [ ] Test installer in dry-run mode +- [ ] Verify v1 detection works +- [ ] Check all remotes push successfully +- [ ] Verify public repo has no sensitive data + +--- + +### 13. Sign-off Checklist | Section | Status | Date | Checked By | |---------|--------|------|------------| @@ -471,6 +552,7 @@ openclaw config get plugins.entries.memory-qdrant | Security review | ⏳ | | | | Multi-remote git | ⏳ | | | | Backup verified | ⏳ | | | +| Known issues reviewed | ⏳ | | | **Final Sign-off:** _______________ **Date:** _______________