From 4f11af2de578843a4614334cba88b5ef462ae3c3 Mon Sep 17 00:00:00 2001
From: clawbot <claw@sneak.berlin>
Date: Sat, 28 Feb 2026 02:22:47 -0800
Subject: [PATCH] add checklists-over-prose section: why redundancy with
 REPO_POLICIES works

---
 OPENCLAW_TRICKS.md | 107 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/OPENCLAW_TRICKS.md b/OPENCLAW_TRICKS.md
index e2b12ca..d4d50f9 100644
--- a/OPENCLAW_TRICKS.md
+++ b/OPENCLAW_TRICKS.md
@@ -683,6 +683,113 @@ turn these soft failures into hard failures:
 The agent doesn't need willpower or attention to detail. It needs a system where
 doing the wrong thing fails loudly.
 
+#### Checklists Over Prose — Why Redundancy Is the Point
+
+REPO_POLICIES.md describes everything: what files are required, how the Makefile
+should work, how formatting works, how CI works. It's comprehensive. But
+comprehensive prose doesn't keep an agent on track — **point-by-point checklists
+do.**
+
+That's why we also maintain two separate checklists alongside REPO_POLICIES.md:
+
+- [**NEW_REPO_CHECKLIST.md**](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md)
+  — step-by-step when creating a repo from scratch
+- [**EXISTING_REPO_CHECKLIST.md**](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md)
+  — step-by-step when starting work in a repo that may not conform yet
+
+These are intentionally redundant with REPO_POLICIES.md. That's the point.
+
+**Why redundancy works for AI agents:**
+
+LLMs are good at linear, sequential processing. Give them a prose document with
+30 requirements scattered across 10 paragraphs, and they'll miss things. Give
+them a numbered checklist where each item is a concrete action with a checkbox,
+and they'll march through it reliably.
+
+The
+[NEW_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md)
+walks through repo creation in five phases:
+
+```markdown
+# 1. Initialize
+
+- [ ] `git init`
+- [ ] Ask the user for the license
+
+# 2. First Commit (README only)
+
+- [ ] Create README.md with all required sections
+- [ ] `git add README.md && git commit`
+
+# 3. Scaffolding (feature branch)
+
+- [ ] Fetch .gitignore, .editorconfig from templates
+- [ ] Create LICENSE, REPO_POLICIES.md, Dockerfile
+- [ ] Configure Makefile with all required targets
+
+# 4. Verify
+
+- [ ] `make check` passes
+- [ ] `make docker` succeeds
+- [ ] No secrets in repo
+
+# 5. Merge and Set Up
+
+- [ ] Merge to main, install hooks, push
+```
+
+The
+[EXISTING_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md)
+does the same for existing repos — check each item, fix gaps before starting
+your actual task:
+
+```markdown
+# Formatting (do this first)
+
+- [ ] Run `make fmt` as standalone commit before any other changes
+
+# Required Files
+
+- [ ] README.md, LICENSE, REPO_POLICIES.md, .gitignore, .editorconfig
+- [ ] Dockerfile, .dockerignore, Gitea Actions workflow
+
+# Makefile
+
+- [ ] All required targets exist and work
+- [ ] `make check` passes
+
+# Git Hygiene
+
+- [ ] Pre-commit hook installed, no secrets, all refs pinned
+
+# Final
+
+- [ ] `make check` passes, `docker build` succeeds
+- [ ] Fix everything before starting your actual task
+```
+
+**The same principle applies everywhere in the agent's configuration.** We have
+checklists for:
+
+- **PR quality gates** (`memory/checklist-pr.md`) — what to verify before
+  pushing, after sub-agent pushes, before assigning to the human
+- **Medication actions** (`memory/checklist-medications.md`) — what to verify
+  before reporting status or sending reminders
+- **Flight actions** (`memory/checklist-flights.md`) — what to verify before
+  stating flight times
+- **Messaging** (`memory/checklist-messaging.md`) — what to verify before
+  sending any message (URLs resolve? times converted? status verified?)
+
+Each checklist is loaded on-demand (referenced from a checklist index at the top
+of MEMORY.md). The agent reads the relevant checklist before the relevant
+action. It's the same pattern as REPO_POLICIES + NEW_REPO_CHECKLIST: prose
+document for understanding, checklist for execution.
+
+**The meta-lesson: AI agents are linear thinkers.** They follow step-by-step
+instructions reliably. They follow scattered prose requirements unreliably.
+Structure your rules as checklists, accept the redundancy, and treat it as a
+feature — not a code smell.
+
 ### Putting It All Together
 
 The system works as a loop: