docs(10.2): capture phase context

2026-02-08 12:16:03 -05:00
parent ac2d745e1d
commit df637c9286
1 changed files with 75 additions and 0 deletions
@@ -0,0 +1,75 @@
 # Phase 10.2: Better Logging & Log Management - Context
 **Gathered:** 2026-02-08
 **Status:** Ready for planning
 <domain>
 ## Phase Boundary
 Improve operational visibility into the bot's own execution. Add centralized error capture, execution tracing, and debugging infrastructure so that issues (sub-workflow data loss, callback routing confusion, Docker API failures) can be diagnosed programmatically rather than through manual investigation of n8n execution logs.
 This is NOT about container log viewing (the /logs command) — it's about the bot's internal execution logging.
 </domain>
 <decisions>
 ## Implementation Decisions
 ### Error capture & reporting
 - Errors display inline to the user as summary + cause (e.g., "Failed to stop nginx: Docker API returned 404 (container not found)")
 - Full diagnostic data (sub-workflow name, node, raw response, stack trace) captured in central error store for Claude's use
 - Only report errors on user-triggered actions — no proactive/unsolicited error notifications
 - Error store uses ring buffer: last 50 errors, auto-rotated
 - Manual clear command also available (/clear-errors or similar, hidden/unlisted)
 ### Execution traceability
 - All sub-workflows report errors back to main workflow for centralized storage
 - Trace data designed for programmatic access — Claude can query it during debugging sessions
 - Hidden/unlisted Telegram commands for quick error checks (e.g., /errors to see recent errors)
 - File-based access also available for deep investigation during debugging sessions
 ### Log output & storage
 - Error/trace data stored in n8n workflow static data (main workflow)
 - Centralized in main workflow — sub-workflows report back, main stores
 - Auto-rotate (ring buffer, 50 entries) + manual clear command
 - Both Telegram commands (quick checks) and file/API access (deep investigation)
 ### Debug mode
 - Debug mode is for Claude's use during debugging — not user-facing
 - Must address three specific pain points:
  1. **Sub-workflow data loss** — capture what data was sent to and received from each sub-workflow at boundaries
  2. **Callback routing confusion** — trace which path a callback took through routing logic
  3. **n8n API execution log parsing** — make execution data easily queryable without manual workflow investigation
 ### Claude's Discretion
 - Trace format and structure (timeline vs. data snapshots vs. both)
 - Whether to trace all executions or only errors (overhead vs. usefulness)
 - Structured entries vs. simple log lines (what enables best debugging)
 - Debug toggle mechanism (global toggle, per-request, or always-on for errors)
 - Log level granularity (on/off vs. error/warn/info)
 - What specific debug data to capture (raw API responses, sub-workflow I/O, timing)
 - Telegram command naming and exact interface
 </decisions>
 <specifics>
 ## Specific Ideas
 - "I want you to be more easily able to track down issues when they occur" — the driving goal is Claude's ability to programmatically diagnose issues
 - Past pain points: sub-workflow boundary data disappearing, callback routing taking unexpected paths, difficulty parsing n8n execution API responses
 - "These logs would resolve these issues" — the logging infrastructure should make the three pain points immediately queryable
 - Error commands should be hidden/unlisted (developer/debug tools, not part of normal command set)
 </specifics>
 <deferred>
 ## Deferred Ideas
 None — discussion stayed within phase scope
 </deferred>
 ---
 *Phase: 10.2-better-logging-and-log-management*
 *Context gathered: 2026-02-08*