hns-lsel-curator

Drain and cluster tool-failure stubs from a JSONL lessons inbox into staged improvement candidates.

1.2k|222|Updated Sep 16, 2025
One-click install
npx skills add https://github.com/modu-ai/moai-adk --skill hns-lsel-curator
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hns-lsel-curator
Source: https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/hns-lsel-curator
Command: npx skills add https://github.com/modu-ai/moai-adk --skill hns-lsel-curator

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq.

What problem does it solve?

Tool-failure observations accumulate in an append-only lessons inbox (.moai/lessons-inbox.jsonl) with no mechanical process to consume them, so recurring failure patterns drown in Bash timeout and sandbox noise and never become actionable improvements.

Core Features & Use Cases

  • Companion-offset drain: Reads new stubs from a persistent offset without mutating the append-only inbox, filtering out Bash timeout/sandbox noise before clustering.
  • Event-key clustering with importance scoring: Groups survivors by event_key, discards singletons, and assigns a 1-10 Generative-Agents-style importance score, staging candidates in clusters.json.
  • Session-start wrapper and reflection: session_drain.sh adds locking, archive-before-overwrite, and fail-open behavior; reflect.sh consolidates accumulated feedback topics into archived principles.
  • Use Case: On each session start, drain the accumulated failure inbox, archive prior candidates, and surface clustered recurring failures (e.g., repeated Agent:UnknownFailure) as shadow proposals for later approval.

Quick Start

Run the session drain wrapper against the lessons inbox to cluster new failure stubs into staged candidates in the LSEL state directory.

Frequently Asked Questions about hns-lsel-curator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I drain a JSONL lessons inbox of tool-failure stubs?

Run session_drain.sh with --inbox pointing to lessons-inbox.jsonl and --state-dir for LSEL state. It acquires a lock, archives any existing clusters.json, then runs drain.sh to filter noise, cluster by event_key, and advance the companion offset.

How does the drain filter out Bash timeout and sandbox noise?

drain.sh applies a drain-side severity filter before clustering, discarding tool_failure:Bash:UnknownFailure, tool_failure:Bash:SandboxViolation, and any event_key ending in :TimeoutError. The filter runs on read because the inbox writer is outside the loop-writable surfaces.

Does the drain modify the lessons inbox or write to memory?

No. The inbox is append-only and never mutated; a companion offset in drain-offset.json marks consumed stubs. Candidates stage only in clusters.json, and the M1 invariant guarantees zero writes to memory/ feedback files.

What happens when two sessions start the drain at the same time?

session_drain.sh uses a mkdir-based exclusive lock; contention results in a safe no-op with a stderr notice and exit 0. Stale locks older than 120 seconds are reaped, and the hook never blocks session start.

Why is the live clusters.json file considered ephemeral?

Every session-start drain overwrites clusters.json, including no-op drains that write empty candidates. The wrapper unconditionally archives the prior file to clusters-history/ first, so proposals must read the archived copies, not the live file.

When does the reflection stage consolidate feedback topic files?

reflect.sh fires when accumulated importance across active feedback_*.md files clears the threshold (default 150) with at least 3 topics, not on a calendar schedule. It synthesizes one principle file and moves originals to memory/_archive/ without deleting them.