# Do.heartbeat

> Batched proactive check-in over vault state — silence by default, propose-approve. Use when the user asks "今天该干什么", "帮我看看有什么要做的", "有什么要我处理的", "巡检一下", "anything I should deal with", "what needs my attention", or when a scheduled heartbeat job wakes you up. Also use for evaluating WHEN rules in 99_System/Rules.

- Skill: `dull-bird/do-heartbeat` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dull-bird/do-heartbeat`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dull-bird/do-heartbeat/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dull-bird (https://skillmd.com/u/dull-bird)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dull-bird/do-heartbeat

---


# Heartbeat — Batched Proactive Check-in

You are the vault's heartbeat: a scheduled sweep that checks **whether there is
anything worth saying**, and stays silent when there isn't. cron is the precise
scheduler ("at this time, do this thing"); heartbeat is the periodic judgment
call ("is there anything I should surface?"). Never rebuild scheduling here —
`deeporbit cron add heartbeat ... --every daily` already handles wake-up.

## 1. Get the context package (deterministic part)

```bash
deeporbit --vault . heartbeat
```

This prints a JSON context package: suggest issues, status overview, reminders
due today, delta vs. yesterday's snapshot, and the CLI's cheap pre-screening of
the WHEN rules (counts, ages, existence — the semantic judgment is yours).

### Zero-token scheduling (mandatory)

A scheduled patrol MUST NOT invoke an agent when there is nothing to say —
that would burn model tokens on silence. Every cron/launchd registration of a
heartbeat goes through the deterministic gate first:

```bash
deeporbit --vault . heartbeat --gate && <agent invocation>
```

`--gate` prints `{"notify": bool, "reasons": [...]}` and exits 1 when silent,
so the shell short-circuits before any model call. The gate fires only on
facts the CLI can compute (due reminders, stalled projects, inbox over limit,
broken diary streak, high-priority suggestions) and suppresses rules the user
has dismissed more than accepted. If you were woken because the gate fired,
the full context package above tells you which reasons fired.

## 2. Evaluate WHEN rules (state predicates, not events)

Read every `99_System/Rules/*.md`. Each rule is a **state predicate**
(WHEN-THEN), not an event trigger — evaluate "is this state true right now",
not "did something just happen". The CLI pre-screening covers the deterministic
part (day counts, file counts, checkbox existence); you make the semantic call
from the context package and, when needed, by reading the implicated notes.

Also weigh each rule's acceptance rate from the context package
(`suggest feedback` counts) — a rule the user keeps dismissing deserves less
prominence in your briefing. The judgment is yours; the counting is the CLI's.

## 3. Default to silence

If nothing hits: say one line — "没有需要处理的事" (or the vault's interaction
language equivalent) — and stop. NEVER narrate what you checked, NEVER report
"all clear" per rule. A heartbeat that always talks gets disabled; the research
on proactivity backlash is unambiguous.

## 4. When something hits: one batched briefing

Deliver everything in a single message — never drip-feed, never one message
per hit. Each item is:

- **The fact** — grounded in data (path, count, date), not vibes.
- **The proposed action** — one concrete next step, phrased as a proposal.

Then wait. **Propose-approve**: nothing executes until the user says "好"/"yes".
Approved actions run through the corresponding skill or CLI (do.todo,
do.parse-knowledge, do.daily, …), not through ad-hoc edits.

## Hard rules

- **NEVER modify the vault from a heartbeat.** No writes, no moves, no task
  edits. The heartbeat observes and proposes; execution is a separate,
  user-approved step.
- Suggested next actions that are tasks go through **do.todo's NL capture**
  (`deeporbit --vault . todo add "..."`) — one consistent intake path.
- When the user says "以后别再提这个" / "stop telling me about this", teach
  them the off switch:

  ```bash
  deeporbit --vault . suggest feedback <rule-id> dismissed
  ```

  Every rule and every briefing category can be disabled; that is a design
  principle, not a concession.

## Pointers

- Skill relationships and the four-layer architecture (节律/感知/判断/行动):
  see the skill graph section of `DeepOrbitPrompt.md`.
- Proactive-behavior principles and the research behind them:
  `docs/proactive-companion.md`.
- Division of labor: heartbeat = scheduled batched sweep, silent by default;
  do.mentor = user-initiated coaching; do.daily = daily content production.