axiom: You cannot improve what you cannot see - observability is prerequisite for scaling

source: IndyDevDan + Alpha Evolve Cycle 3

category: observability

genesis_action: All agent sessions must log events via PostToolUse hook


axiom: Tool calls approximately equal impact - measure agent productivity by tool call volume

source: IndyDevDan Thread Engineering

genesis_action: Track total_tool_calls as primary productivity metric in observability dashboard


axiom: Event streams must never block execution - all logging is best-effort

source: Production observability patterns

genesis_action: observability_logger.py wraps all operations in try/except, never raises


axiom: Sanitize before logging - never persist secrets, truncate large payloads

source: Security best practices

genesis_action: Redact api_key/token/password/secret fields, truncate content to 200 chars


axiom: Classify events by category for actionable metrics - orchestration vs file_ops vs execution

source: Alpha Evolve Cycle 3

genesis_action: Every event tagged with category for aggregation in query tool


axiom: Track agent identity per event for multi-agent attribution

source: IndyDevDan Multi-Agent Observability

genesis_action: Every event captures session_id, agent_id, agent_name, team_name from environment


axiom: Orchestration events deserve special attention - they reveal coordination patterns and bottlenecks

source: IndyDevDan Multi-Agent Orchestration

genesis_action: Query tool has dedicated --orchestration flag filtering team/task/message events


axiom: Post-session analysis enables continuous improvement of agent prompts and workflows

genesis_action: Run observability summary after every Agent Team session to identify optimization opportunities


axiom: Agent lifecycle events (spawn/stop) are as important as tool calls - they reveal team dynamics and bottlenecks

source: Alpha Evolve Cycle 4

genesis_action: SubagentStart and SubagentStop hooks track full agent lifecycle with active count metrics


axiom: Error tracking via PostToolUseFailure enables proactive debugging - failures caught at source, not downstream

genesis_action: PostToolUseFailure hook captures error preview and tool context for --errors query


axiom: One universal logger with event dispatch is better than many specialized scripts - single codebase, all event types

genesis_action: observability_logger.py uses --event flag dispatch table for 6 event types from one script


axiom: Session lifecycle tracking completes the observability picture - know when sessions start and end, not just what happens during them

genesis_action: Stop hook logs session_stop events and writes to sessions.jsonl for session-level analysis


axiom: Correlation IDs are the backbone of distributed tracing - without them, multi-agent events are disconnected islands

source: Alpha Evolve Cycle 7 - P0 Gap Fix

genesis_action: Every event automatically gets correlation_id from GENESIS_CORRELATION_ID env, CLAUDE_SESSION_ID, or generated UUID


axiom: Parent-child trace relationships enable full call tree reconstruction across agent boundaries

genesis_action: Agent spawn events capture parent_agent, child_agent, and trace_depth for call tree visualization


axiom: Trace queries reconstruct request flow: filter by correlation ID, group by agent, show parent-child tree, render timeline

genesis_action: observability_query.py --trace ID shows agents involved, call tree, and chronological timeline for any correlation