# Periodic review

> Daily followups (--due today), weekly doctor + overdue sweep, monthly mission-drift checks, and closure rules for checkAt-bearing artifacts.

- Repository: superdesigndev/loopany
- GitHub: https://github.com/superdesigndev/loopany
- Human docs: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8
- Complete Markdown: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8/llms-full.txt

## Source Files

- `skills/loopany-review/SKILL.md`
- `skills/loopany-review/references/daily.md`
- `skills/loopany-review/references/weekly.md`
- `skills/loopany-review/references/monthly.md`
- `src/commands/followups.ts`
- `src/commands/doctor.ts`

---

---
title: "Periodic review"
description: "Daily followups (--due today), weekly doctor + overdue sweep, monthly mission-drift checks, and closure rules for checkAt-bearing artifacts."
---

Periodic review is implemented as the `loopany-review` skill pack (`skills/loopany-review/`) plus deterministic CLI queries (`loopany followups`, `loopany doctor`). The harness returns candidates; the agent classifies, surfaces only judgment-needed items, dispatches to per-kind playbooks, and must close every surfaced item before ending the session.

## Role in the loop

| Layer | Responsibility |
|-------|----------------|
| `loopany-resolver` | Routes phrases like "what's due today", "weekly check", or "is this still the right mission?" to `loopany-review` |
| `loopany-review` | One skill, three frequencies; shared classify → surface → dispatch → **close** gate |
| `loopany followups` | Index scan: artifacts with `checkAt` on or before a cutoff date |
| `loopany doctor` | Integrity checks (workspace, schema, kinds, artifacts, references, onboarding, warnings) |

<Note>
Review is judgment-heavy and runs inside an agent session. `INSTALL_FOR_AGENTS.md` treats bare shell cron as insufficient for weekly/monthly work; coding CLIs default to session-boundary prompts instead of durable cron registration.
</Note>

## Cadence routing

Do not mix scopes across frequencies — one day of overdue is not a weekly pattern; one week cannot prove mission drift.

| Frequency | Scope | Typical trigger | Reference |
|-----------|-------|-----------------|-----------|
| **Daily** | `checkAt` due **today** (not overdue backlog) | Session start, "what's due today" | `skills/loopany-review/references/daily.md` |
| **Weekly** | Overdue `checkAt`, `doctor`, parking-lot sweeps | "What's slipping", "weekly check", workspace health | `skills/loopany-review/references/weekly.md` |
| **Monthly** | Active mission alignment, structural drift (domains/kinds) | "Right mission?", "anything structural?" | `skills/loopany-review/references/monthly.md` |

```mermaid
flowchart TB
  subgraph triggers [Resolver triggers]
    T1["what's due today"]
    T2["weekly check / slipping"]
    T3["right mission? / structural?"]
  end
  subgraph skill [loopany-review]
    D[daily.md]
    W[weekly.md]
    M[monthly.md]
    U["Unified flow: classify → surface → dispatch → close"]
  end
  subgraph cli [Deterministic CLI]
    F["loopany followups"]
    DOC["loopany doctor"]
    AL["loopany artifact list/get/status/set"]
  end
  T1 --> D --> U
  T2 --> W --> U
  T3 --> M --> U
  D --> F
  W --> F
  W --> DOC
  M --> AL
  U --> AL
```

## Unified review flow

All frequencies share the same pipeline after frequency-specific queries.

<Steps>
<Step title="Query">
Run the commands from the daily, weekly, or monthly reference file.
</Step>
<Step title="Classify">
For each candidate: `loopany artifact get <id>`.

- **A — Silently resolvable:** extend `checkAt` with a one-line reason (no user prompt).
- **B — Needs the user:** judgment or data only the user has.
- **C — Defer:** push `checkAt` forward **with a reason** ("not yet" is invalid).

For `learning` artifacts, add context: `loopany trace <learning-slug> --direction backward`.
</Step>
<Step title="Surface">
Emit only bucket **B** items. One line each. If empty, say so and stop — quiet is correct.
</Step>
<Step title="Dispatch">
Route to kind playbooks under `skills/loopany-core/kinds/` (`task`, `learning`, `signal`, `mission`).
</Step>
<Step title="Close (gate)">
Every surfaced item must end as **resolved**, **deferred**, or **retired** before the session ends. A digest without state changes is noise.
</Step>
</Steps>

### Closure outcomes

| Outcome | Meaning | Typical writes |
|---------|---------|----------------|
| **Resolved** | Question answered or work finished | `loopany artifact status`, required `## Outcome` on terminal task statuses; signal → `addressed` with `--addressed-by` |
| **Deferred** | Revisit later with intent | `loopany artifact set <id> --field checkAt --value <YYYY-MM-DD>` plus reason in body or append |
| **Retired** | No further scheduled check | Remove follow-up obligation (`checkAt` cleared or artifact reaches terminal status) with a note |

```mermaid
stateDiagram-v2
  [*] --> Surfaced: bucket B item
  Surfaced --> Resolved: status transition + evidence
  Surfaced --> Deferred: checkAt pushed with reason
  Surfaced --> Retired: checkAt removed or terminal status
  Resolved --> [*]
  Deferred --> [*]
  Retired --> [*]
  note right of Surfaced
    No zombie items:
    session must not end
    with open surfaced items
  end note
```

## Daily review

**Query**

```bash
loopany followups --due today
```

**Rules**

- Process only items whose `checkAt` date equals **today**. The CLI returns every artifact with `checkAt <= today`, which includes overdue rows — leave those for weekly (`--due overdue`).
- At most once per day.
- Empty result → report "nothing due today" and stop.

**Example surface format** (from the skill; slugs are illustrative):

```
3 things need you today:
1. [<task-slug>] 2-week recheck — did $/session settle?
2. [<learning-slug>] "short deals close 2.5x faster" — still true?
3. [<signal-slug>] recurring churn signal, 3rd time. Upgrade?
```

`learning` revalidation on `checkAt` belongs in daily review, not `loopany-reflect` (reflect looks forward; review looks back at scheduled checks).

## Weekly review

**Query**

```bash
loopany followups --due overdue
loopany doctor --format json
```

Plus parking-lot lists (agent-run `artifact list`, not a separate CLI):

| Parking lot | Command | Threshold |
|-------------|---------|-----------|
| Stalled tasks | `artifact list --kind task --status running` | ≥ 14 days, no recent append |
| Stale signals | `artifact list --kind signal --status open` | ≥ 7 days, no action |
| Pending proposals | `artifact list --kind skill-proposal --status pending` | any → mention; > 5 → nudge |

**Doctor handling**

Summarize by category and propose fixes. Do **not** auto-fix — failures may reflect an in-progress decision.

Stalled `running` tasks should move to `in_review`, `failed`, or `cancelled` with `## Outcome`. "Still working on it" is not closure.

**Feed reflect**

If the weekly pass resolves ≥ 3 items, suggest `loopany-reflect` (pattern extraction is reflect's job, not doctor's).

## Monthly review

**Query**

```bash
loopany artifact list --kind mission --status active
```

Plus recent tasks (~30 days) for alignment math.

**Mission alignment** (from `skills/loopany-core/kinds/mission.md`):

```
alignment = tasks mentioning this mission / total recent tasks
```

| Alignment | Action |
|-----------|--------|
| ≥ 60% | Healthy |
| 30–60% | Partial drift — backfill `mentions` or add a second mission? |
| < 30% | Clear drift — propose re-onboarding |

Monthly surfaces hypotheses; the user decides. Do not auto-abandon missions.

**Structural drift — domains** (all three required before proposing a `[change]` task):

1. ≥ 5 artifacts tagged with an unenabled domain
2. ≥ 2 weeks of accumulation
3. Scope distinguishable from existing domains

**Structural drift — kinds** (both required):

1. ≥ 3 `note` artifacts sharing a body skeleton for ≥ 2 weeks
2. Passes the four-question kind test in `skills/loopany-core/conventions/taxonomy.md`

Forward-only: propose new structure; do not migrate existing artifacts in review.

## `checkAt` and `loopany followups`

`checkAt` is optional frontmatter on kinds that index it (`task`, `learning`, `skill-proposal`, …). Set it only with a concrete future question — missing `checkAt` is better than a date you will ignore.

The in-memory index (`src/core/index.ts`) selects artifacts where `checkAt` (YYYY-MM-DD prefix) is on or before the cutoff date. `src/commands/followups.ts` adds filters:

<ParamField body="--due" type="today | overdue | next-7d" default="today">
Cutoff for the index scan. `next-7d` extends the cutoff seven days ahead (implementation supports it; `--help` lists `today` and `overdue` only).
</ParamField>

<ParamField body="--include-done" type="true">
When `true`, includes artifacts whose `status` has no outgoing transitions in the kind status machine (e.g. `done`, `cancelled`, `failed` on tasks).
</ParamField>

<ParamField body="--domain" type="string">
Restricts results to matching `frontmatter.domain`.
</ParamField>

| `--due` value | Index cutoff | Extra filter |
|---------------|--------------|--------------|
| `today` (default) | `checkAt <= today` | None |
| `overdue` | `checkAt <= today` | `checkAt` date **strictly before** today |
| `next-7d` | `checkAt <= today + 7 days` | None |

**Output:** JSON array of `ArtifactMeta` on stdout (same as other query commands).

**Create / defer examples**

```bash
loopany artifact create --kind task --title "Recheck API rate limits" \
  --status todo --check-at 2026-06-12

loopany artifact set <id> --field checkAt --value 2026-07-01
```

E2E coverage: `test/cli.e2e.test.ts` (`loopany followups` describes terminal-status filtering); lifecycle scenario in `test/scenario.e2e.test.ts` (signal → task with `checkAt` → `followups --due today` → `done`).

## `loopany doctor`

Doctor is integrity-only: deterministic checks, no semantic body scans (TODO hunting belongs in reflect).

| Check | Pass | Fail / warn behavior |
|-------|------|----------------------|
| `workspace` | Bootstrap path + kinds dir | — |
| `schema version` | `config.schemaVersion` matches binary `SCHEMA_VERSION` | Fail; message points to `loopany migrate` |
| `kinds` | All kind defs parse | Fail lists broken files |
| `artifacts` | Every frontmatter passes kind Zod schema | Fail lists invalid IDs |
| `references` | No dangling `from`/`to` | Fail lists broken edges |
| `onboarding` | `self` person + ≥1 active `mission` | Fail with onboarding hint |
| `mission coverage` | (warn) every `task` mentions a mission | Warn lists orphans |
| `domain coverage` | (warn) artifact `domain` ∈ `enabled_domains` | Warn lists unenabled domains |

<CodeGroup>
```bash title="Human-readable"
loopany doctor
```

```bash title="JSON (weekly review)"
loopany doctor --format json
```
</CodeGroup>

Exit code is non-zero when any check has `status: fail`. Warnings do not fail the run.

Version check is bypassed during doctor bootstrap so a mismatch is reported instead of crashing early.

## Boundaries and anti-patterns

| Mistake | Why it fails |
|---------|----------------|
| Daily pass processes overdue backlog | Steals weekly scope; skill explicitly forbids |
| Weekly pass re-runs daily due-today | Nothing should stagnate in 24h at weekly granularity |
| Monthly pass duplicates weekly parking lots | One week cannot prove structural drift |
| Defer without reason | Items rot silently |
| Surface without close | Worse than no digest |
| Dump raw `followups` JSON | Agent job is judgment, not relay |
| Run reflect for due `learning` checks | Scheduled revalidation is daily review |

## Registering cadence

On install, agents pick one path silently (`INSTALL_FOR_AGENTS.md`):

- **Durable cron hosts (Hermes, OpenClaw, …):** register `loopany-review` (and `loopany-reflect` weekly) on schedule inside agent sessions; record job IDs for audit.
- **Coding CLIs (default):** do not register cron (e.g. Claude Code `CronCreate` expires ~7 days). Instead: session start → daily `followups`; week-end → weekly doctor + overdue; month-end → mission review.

The user hears a single plain-language cadence sentence at onboarding close — not host-internals menus.

## Related pages

<CardGroup>
<Card title="Graph, search, and scheduling" href="/graph-search-commands">
`followups` flags, JSON output, and terminal-status filtering in full command context.
</Card>
<Card title="Doctor and troubleshooting" href="/doctor-and-troubleshooting">
Per-check failures, exit codes, and recovery alongside `migrate` / `reindex`.
</Card>
<Card title="Reflect workflow" href="/reflect-workflow">
Weekly feed when ≥3 resolutions; learnings and skill-proposals — not daily `checkAt` revalidation.
</Card>
<Card title="Self-improvement loop" href="/self-improvement-loop">
`checkAt` on accepted skill-proposals and learning beliefs that daily/weekly review closes.
</Card>
<Card title="Workspace setup" href="/workspace-setup">
`loopany init`, onboarding, and cadence registration expectations after install.
</Card>
<Card title="Skills library" href="/skills-library">
Resolver routing table and cross-skill chaining (review → core, review → reflect).
</Card>
</CardGroup>