Watcher Design Worksheet
What this is. The worksheet every watcher passes before it runs. Response test, condition-and-threshold, quiet-run behavior, event-ID strategy, bias statement, register fields, and a pre-launch checklist.
How to use. Work through the seven sections in order. Section 1 is a gate — if the response test fails, stop. Do not build a watcher that will ping you without a real routing action attached. When every box in section 7 is checked, proceed to the recipe and build.
A watcher fires. Briefs, reports, and refreshes produce.
If it cannot fire — if it runs every day whether or not the condition is met — it is not a watcher. It is a brief.
1. The response test — fill this in first
Answer in one sentence each. If you cannot answer any of these three, stop — this watcher is not worth building.
e.g., “Open the thread it flagged, read it, draft a reply in my drafts folder and send within 60 minutes.”
Real routing / “see what’s up” — honest answer.
Yes / probably / probably not — honest answer.
If any of the three is a problem, the watcher does not proceed to build. Return to the idea list in Lesson 6.5’s callout, or pick a different event to watch.
2. Condition-and-threshold statement
Fill in the four parts. Each part is one sentence, specific and auditable.
The concrete thing that triggers the watcher. Specific sender, specific calendar event type, specific keyword, specific threshold crossing.
The extra conditions the event must satisfy.
What changed meaningfully since the last run (so the watcher does not fire repeatedly on the same event).
What explicitly does not fire.
3. Quiet-run behavior
The standard language is pre-written; change only if you have a specific reason.
On runs where the condition is not met, the watcher writes one line to <LOG_PATH> in the form:
and exits without creating any artifact file.
4. Firing behavior
The stable identifier used for deduplication so the watcher fires exactly once per unique event. (e.g., the email’s RFC 822 Message-ID header — specifically, the first Message-ID of the root email in the thread.)
Where the firing artifact lands. (e.g., ~/ai-architect-academy/automation/watchers/<watcher-name>/fires/<event-id>.md)
One header line, one sentence of why it fired, a pointer to the triggering thread/event, and your response-test action restated. Use the shape above unless you have a specific reason to differ.
5. Bias statement
Every watcher tolerates one failure mode more than the others. State yours explicitly so future-you does not second-guess the design.
One sentence — why.
If it biases toward false positives, the qualifier and non-event sections should be permissive (fewer exclusions, more fires, more misses avoided). If it biases toward false negatives, the qualifier and non-event sections should be strict (more exclusions, fewer fires, occasional misses acceptable).
The module’s default recommendation for most first watchers is bias toward false negatives. Exceptions — for watchers on events you cannot afford to miss (college admissions, scholarship deadlines, legal deadlines) — should flip this bias and tighten the response-test commitment accordingly.
6. Register-entry fields
These are the non-shared register fields for this watcher. Copy into the register row when you file entry 4.
- Task name: Watcher — <name>
- Schedule: <e.g., “every 4 hours, 07:00–23:00 America/New_York”>
- Scope / credentials: <the narrowest inputs/permissions the watcher needs>
- Idempotency key: <your Event ID strategy from section 4>
- Artifact path: <your firing-artifact path from section 4>
- Cost ceiling: <per-run and per-month — watchers typically have many runs, so the per-month number matters>
- Retirement trigger: <the specific real-world event that would make this watcher irrelevant — the case decided, the deadline past, the project concluded>
7. Pre-launch checklist
When every box is checked, proceed to the recipe to build and launch the watcher.