gtapps/reflect-scheduled-checks

Reflect Scheduled Checks

Standalone routine skill. Runs at most one due interval-triggered scheduled check per invocation, gates any findings through the normal proposal pipeline, applies state, and appends a Progress Log entry. Invoked by the scheduled-checks routine (daily, offset from reflect).

What counts as a scheduled check

Any skill registered in config.scheduled_checks that satisfies this contract:

• Idempotent — running twice in a row is safe.
• Returns findings or nothing — either a concrete actionable/contextual observation, or silence.
• No self-scheduling — cadence is owned by scheduled_checks.interval_days.
• Short-running, read-mostly — does not block or produce side effects on success.

Steps

1. Load context

Read config.json → scheduled_checks (filter to enabled: true, trigger: "interval").

Read state/reflection-state.json → scheduled_checks (per-check state: last_run, last_unavailable_at, last_error_at, consecutive_empty).

2. Filter due checks

From the enabled interval entries, keep those where:

• last_run is null or older than interval_days days, AND
• last_unavailable_at is null or older than 4 hours (transient cooldown — skill may have been briefly unavailable), AND
• last_error_at is null or older than interval_days days (persistent back-off for true errors)

3. Pick one

Select the entry with the oldest last_run (null sorts first). If none are due, skip to the Progress Log (§ 7) with outcome skipped.

4. Invoke

Invoke the skill command string as-is, using the Skill tool. Do not "verify installation" first — the harness's loaded-skills list (shown in system-reminders) is authoritative. In particular, never grep ~/.claude/plugins/cache/ or any plugin directory to check whether a plugin is installed — the cache layout is cache/<marketplace>/<plugin>/, not cache/<plugin>/, and assumption-based path checks have produced false-negative unavailable outcomes.

Classify the result:

• The skill name is not present in the available-skills list, or the Skill tool rejects it as unknown → outcome: unavailable
• The skill runs but errors or times out → outcome: error
• The skill runs to completion → evaluate the output (step 5)

5. Evaluate

• Actionable improvement found → outcome: actionable, summarize finding
• Context improvement (e.g., CLAUDE.md fix) → outcome: contextual, summarize finding; apply directly if trivial
• Nothing found → outcome: empty

6. Act on outcome

actionable / contextual:

Pass through the Evidence Validation gate:

Candidate: <title derived from finding>
Tier: 1
Evidence Source: scheduled-check/<id>
Evidence: <one-paragraph summary>
Sessions: none

Delegate to claude-code-hermit:reflection-judge. On ACCEPT (scheduled-check) or DOWNGRADE, proceed to claude-code-hermit:proposal-triage with:

Title: <title>
Evidence Source: scheduled-check/<id>
Evidence: <summary>

Parse line 1 as the verdict. Lines 2+ are additive metadata (closest_prop, aligned, operator_excerpt, overlap_compiled, prior_discussion, failed_condition) — read for context if useful but do not branch on them.

After receiving the verdict, append one event to state/proposal-metrics.jsonl:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/append-metrics.ts \
  .claude-code-hermit/state/proposal-metrics.jsonl \
  '{"ts":"<now ISO>","type":"triage-verdict","verdict":"<CREATE|SUPPRESS|DUPLICATE>","caller":"scheduled-checks"}'

• Triage CREATE → classify tier. Tier 1/2: queue micro-approval (§ Micro-approval queuing). Tier 3: call /claude-code-hermit:proposal-create directly.
• Triage SUPPRESS or DUPLICATE → drop silently; note in SHELL.md Progress Log.
• Unrecognized triage line 1 (agent errored, returned malformed/empty output, or was terminated before emitting a verdict): fail closed — skip the triage-verdict append. Append:

  bun ${CLAUDE_PLUGIN_ROOT}/scripts/append-metrics.ts \
    .claude-code-hermit/state/proposal-metrics.jsonl \
    '{"ts":"<now ISO>","type":"gate-failed","agent":"proposal-triage","title":"<title>"}'
  

  Note gate-failed: proposal-triage — <title> in the SHELL.md Progress Log. The candidate re-surfaces on the next scheduled-checks run.

On SUPPRESS from reflection-judge → drop silently. On unrecognized verdict from reflection-judge (malformed/empty output): fail closed — treat as SUPPRESS. Append:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/append-metrics.ts \
  .claude-code-hermit/state/proposal-metrics.jsonl \
  '{"ts":"<now ISO>","type":"gate-failed","agent":"reflection-judge","title":"<title>"}'

Note gate-failed: reflection-judge — <title> in the SHELL.md Progress Log. The candidate re-surfaces on the next scheduled-checks run.

empty:

No proposal candidate. Increment consecutive_empty counter in state (§ State update). Check interval-adjustment logic (§ Interval adjustment proposals).

unavailable:

Note in SHELL.md ## Findings: Scheduled check skipped: <id> — skill unavailable (cooldown 4h). No candidate.

error:

Note in SHELL.md ## Findings: Scheduled check error: <id> — retrying after interval_days. No candidate.

skipped: No action except Progress Log.

Micro-approval queuing

Every micro-proposal question must include: [observed pattern + duration] + [consequence] + [exact proposed change] + "Yes / No"

Queuing procedure:

1. Generate ID: MP-YYYYMMDD-N where N increments within the same day (0, 1, 2). Check existing micro-queued events in proposal-metrics.jsonl for today to determine N.
2. Append micro-queued event to proposal-metrics.jsonl first (so a partial failure leaves a recoverable orphaned event, not a silent ghost entry):

   bun ${CLAUDE_PLUGIN_ROOT}/scripts/append-metrics.ts .claude-code-hermit/state/proposal-metrics.jsonl <<'HERMIT_METRICS_JSON'
   {"ts":"<now ISO>","type":"micro-queued","micro_id":"MP-YYYYMMDD-N","tier":1,"question":"<full question text>"}
   HERMIT_METRICS_JSON
   

3. Read state/micro-proposals.json. Append a new entry to pending with id: "MP-YYYYMMDD-N", tier: <1|2>, status: "pending", follow_up_count: 0, ts: "<now ISO>", question: "<full question text>". Write the file.
4. Notify the operator with the question.

Interval adjustment proposals

Using the current consecutive_empty value (after update in § State update):

Reset rules:

• empty outcome → consecutive_empty += 1
• actionable / contextual outcome → consecutive_empty = 0
• Interval-increase proposal accepted or dismissed → reset to 0

Proposals (standard Three-Condition Rule, not tagged scheduled-check):

• 3+ consecutive empty runs → create a proposal to increase interval_days (e.g., 7 → 14). Three occurrences = repeated pattern; high interval_days means the check never fires usefully = meaningful consequence; operator approves the config change = actionable. Pass through claude-code-hermit:proposal-triage before creating.
• 3+ actionable findings in a single run → not applicable (one check per invocation by design).

Adjustments always go through PROP-NNN — this skill never auto-adjusts.

7. State update

Write the state delta directly to state/reflection-state.json → scheduled_checks.<id>:

bun -e "
const fs=require('fs');
const f='.claude-code-hermit/state/reflection-state.json';
try {
  const s=JSON.parse(fs.readFileSync(f,'utf-8'));
  if(!s.scheduled_checks) s.scheduled_checks={};
  const id='<check-id>';
  if(!s.scheduled_checks[id]) s.scheduled_checks[id]={};
  const c=s.scheduled_checks[id];
  // Set fields according to outcome — only set fields that should change
  // outcome=unavailable: c.last_unavailable_at='<ISO>'; (leave last_run unchanged)
  // outcome=error:       c.last_error_at='<ISO>'; (leave last_run unchanged)
  // outcome=empty:       c.last_run='<ISO>'; c.consecutive_empty=<prior+1>;
  // outcome=actionable|contextual: c.last_run='<ISO>'; c.consecutive_empty=0;
  fs.writeFileSync(f, JSON.stringify(s,null,2)+'\n','utf-8');
} catch(e){ process.stderr.write('scheduled-checks state: '+e.message+'\n'); }
"

Substitute the actual id, ISO timestamp, and field assignments for the current outcome before running. Always exits cleanly — a failed write is logged to stderr only.

8. Progress Log Entry (always)

Append one line to .claude-code-hermit/sessions/SHELL.md under ## Progress Log:

[HH:MM] scheduled-checks — <id>: <outcome>; verdicts: accept=A downgrade=D suppress=S; outcome: <none|micro-queued|proposal-created|interval-proposal>

Use skipped for the id field and skipped for outcome when no check was due.