Appendix E: Common Patterns Reference

This appendix serves as a compressed quick reference for the patterns used throughout the handbook. When you're mid-implementation and need a fast reminder of how something works — the SOUL.md structure, cron syntax, Python script template, error handling patterns — this is where you look. It deliberately sacrifices depth for breadth, covering more patterns in less space than the main chapters.

The context file patterns cover the canonical structure for SOUL.md (Identity, Principles, Communication Style, Domain Context, Keyword Commands, Always Do, Never Do), MEMORY.md (Routing Decisions, Operator Preferences, System Configuration, Known Issues, Escalation Patterns), and AGENTS.md (Role, Named Agents, Routing Rules, Quality Gates, Escalation Protocol, Memory Protocol). These structures are the foundation of every well-configured OpenClaw installation — getting them right means your agent behaves consistently and predictably.

The Python script template is used throughout the cookbook and represents the standard shape of a production automation script: configuration at the top, input validation, main processing logic with structured result dict, output saving with parent directory creation, and a main() function that outputs a summary for agent consumption. Following this template means every script is immediately understandable to anyone familiar with the pattern.

Deep dive sections extend the appendix into advanced territory: exec tool behavior (environment variables, working directory, timeout handling, PTY mode, security modes), web scraping at scale (rate limit respect, pagination handling, caching), memory architecture at scale (tiered memory with CORE.md/CURRENT.md/ARCHIVE/DAILY, searchable memory via grep, monthly compaction), debugging agent behavior (reading agent logs, adding instrumentation, the replay pattern with checkpoints, prompt debugging via binary search), production hardening (idempotency requirement, health check endpoints, graceful shutdown), working with external APIs (API key auth, OAuth token refresh, rate limit handling), building reliable outputs (schema validation, sanity checks against history, diff-based change detection), and building custom skills (trigger design, input/output/failure definition, Weekly Review Skill example).

Key Items

• **Context File Structures** — Canonical templates for SOUL.md (Identity/Principles/Communication Style/Domain Context/Keyword Commands/Always Do/Never Do), MEMORY.md (Routing Decisions/Operator Preferences/System Configuration/Known Issues/Escalation Patterns), and AGENTS.md (Role/Named Agents/Routing Rules/Quality Gates/Escalation Protocol/Memory Protocol); adherence to these structures enables predictable agent behavior
• **Python Script Template** — Standard production script shape: pathlib configuration, logging setup with file + stream handlers, input validation with exit on bad input, structured result dict, output persistence with parent directory creation, main() that prints agent-readable JSON summary; used throughout the cookbook
• **Error Handling Patterns** — Retry with exponential backoff (with_retry), graceful degradation with fallback data sources, and state tracking for resumable processes; each pattern handles a distinct failure mode and can be composed into larger pipelines
• **Multi-Agent Coordination Templates** — Research handoff (project initiation with required artifacts and gate decision), Implementation handoff (sprint plan + story format + DONE criteria), and RALPH escalation message format (blocked phase, agent, attempts, error details, tried approaches, partial artifacts, recommended options); standard formats enable reliable inter-agent communication
• **Production Hardening Patterns** — Idempotent operations (prefer snapshot writes over appends), health check endpoints (zero if healthy, 1 if degraded), and graceful shutdown (signal handlers that finish current item before exiting); these patterns distinguish "works on my machine" from "runs reliably for months"

Related Concepts

• [[kelly-handbook-ch2-core-context-files]] for context file deep dives
• [[kelly-handbook-ch3-file-automation]] for file operations and scripting patterns
• [[kelly-handbook-ch5-error-handling]] for error handling deep dive
• [[karpathy-llm-wiki]] for the LLM wiki pattern this KB follows