Alex/true-recall
1
0
Fork 0
Code Pull Requests Activity

docs: Add Known Issues section to checklist

Browse Source 
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
This commit is contained in:
root
2026-02-24 21:43:57 -06:00
parent a22e6f095a
commit abc5498f60
1 changed files with 83 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
checklist.md
View File

@@ -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 (`<QDRANT_IP>`, 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:** _______________