brain-insights

The brain's proactive channel. Everything else Robert's OS surfaces answers a question he asked or reports a run he scheduled. This skill answers the question he did NOT ask: "what about me got better while you weren't looking?"

Detects three kinds of change over a rolling 24h window, deterministic (no LLM):

• capability - a skill's frontmatter flipped from any prior state to

graduation: graduated. The skill now has a sidecar script and auto eval that didn't exist yesterday.

• pitfall - a loader (state/skills/<name>/AGENTS.md) gained a new

bullet under ## Known Pitfalls. That rule now rides with every prompt mention of <name>, but the operator was never told.

• parity - a runtime's mean score in state/log/parity.ndjson rose

at least 0.10 when comparing the last 24h to the 24h before.

Each run appends to state/log/insights.ndjson; the byline shows one 💡 row with the unread count, cleared when the operator runs this skill.

Usage

# The byline shows "💡 N new insights"
# Operator runs:
/brain-insights                       # show unread, advance cursor (default "read")
npx tsx state/bin/brain/insights.ts   # scan for new insights (what the cron does)
npx tsx state/bin/brain/insights.ts --list   # preview without advancing cursor
npx tsx state/bin/brain/insights.ts --ack    # mark everything read without showing

Shape

Each row in state/log/insights.ndjson:

{
  "ts": "2026-04-18T22:04:23Z",
  "kind": "capability|pitfall|parity",
  "summary": "one-paragraph human description",
  "evidence_path": "state/skills/<name>.md",
  "one_line_for_byline": "<8-12 char pithy phrase>",
  "key": "capability-<sha1-10>"
}

key dedups - the same graduation, pitfall, or parity bucket won't emit twice. The cursor lives at state/log/byline-insights-cursor.json as {last_ts, written}.

Cron

Scheduled every 30 minutes, matching the breaker cadence:

15,45 * * * * /Users/robertboulos/projects/snappy-os/state/bin/brain/insights-cron.sh

Eval

auto (shape gate): the script must produce at least the output scanned. N new insight(s)... with N >= 0. Cursor must never regress (monotonic). Contract tested in the integration: new graduation event in git → next scan emits exactly one new row for that skill.

Known Pitfalls

• The 24h baseline is git rev-list -n 1 --before="24 hours ago" HEAD.

If the branch has no commit in the last 24h the baseline is HEAD itself, which means no graduation diffs surface. That's correct behavior (nothing changed in the last 24h) but can feel surprising.

• Parity insights bucket once per day per runtime: a sustained climb

won't re-surface at every 30-min tick.

• The fixer adds pitfalls under ## Known Pitfalls; the detector

currently scans any loader diff in that section, not just fixer-auto-added ones. Manual edits to loader pitfalls will also surface - that's intentional but worth naming.

Rubric

criteria:
  - name: generates_valid_json_output
    kind: deterministic
    check: "The command `/brain-insights --list` produces an array of JSON objects, each matching the specified 'Shape' in SKILL.md."
  - name: cursor_advances_on_read
    kind: deterministic
    check: "After running `/brain-insights` (default 'read' mode), the 'last_ts' field in `state/log/byline-insights-cursor.json` is updated to a timestamp greater than or equal to the 'ts' of the last displayed insight."
  - name: new_insights_detection
    kind: deterministic
    check: "If a skill's frontmatter changes to `graduation: graduated` within the last 24 hours, running `npx tsx state/bin/brain/insights.ts` results in a new entry in `state/log/insights.ndjson` with `kind: \"capability\"` related to that skill."
  - name: pitfall_detection_accuracy
    kind: deterministic
    check: "If a new bullet is added under `## Known Pitfalls` in a loader (`state/skills/<name>/AGENTS.md`), running `npx tsx state/bin/brain/insights.ts` generates a new entry in `state/log/insights.ndjson` with `kind: \"pitfall\"` referencing that loader."

brain-insights - loader

Per-turn rules for the brain-insights skill. Full reference: state/skills/brain-insights/SKILL.md. Do not skip these.

Critical Rules

• NEVER edit state/log/insights.ndjson by hand. Append-only. Rows are deduped by key, so editing breaks the dedup contract.
• NEVER write to the cursor directly. Use the script's --ack or --read to advance it atomically.
• ALWAYS prefer --read for interactive operator use - it advances the cursor. --list is preview-only and keeps insights unread.
• The detector is deterministic - no LLM. If you find yourself dispatching a model to decide what's an insight, stop. The three kinds are precisely defined; add a new detector in code instead.

Commands

| ui dashboard | state/skills/brain-insights/resources/ui.openui | |invoke: npx tsx state/bin/brain/insights.ts (scan) |interactive: npx tsx state/bin/brain/insights.ts --read (show + ack) |preview only: npx tsx state/bin/brain/insights.ts --list |log: state/log/insights.ndjson |cursor: state/log/byline-insights-cursor.json |eval log: state/log/evals.ndjson (skill: "brain-insights")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/brain-insights/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• git rev-list -n 1 --before="24 hours ago" HEAD can return HEAD itself when the branch has no commit in the last 24h. That's correct (nothing changed) but can feel like a bug.
• Parity insights use a date-bucket key; they surface at most once per day per runtime even if the detector is scanned every 30 min.

Self-Test

An agent reading this should correctly:

1. [ ] Use the script, not direct ndjson writes, to append insights?
2. [ ] Use --read when an operator asks to see insights (so the cursor advances)?
3. [ ] Understand that the detector must stay deterministic - no LLM?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] brain-insights: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] brain-insights: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.