Skip to content

tvproductions/gzkit / .agents/skills/gz-insights-remember

gz-insights-remember

Verified

Use when the operator course-corrects or a defect, resolution or discovery needs recording through gz insights remember.

gz insights remember

Purpose

Wield gz insights remember to append one schema-valid record to the append-only insights store at .gzkit/insights/agent-insights.jsonl (GHI #575). The store accumulates four trust-bearing record kinds — defect, defect-resolution, improvement, discovery — and was historically hand-appended, which drifted from the InsightRecord schema (date-only timestamps, malformed evidence, missing required fields). remember closes that gap: it constructs an InsightRecord first (validating type, scope, summary) and only then serializes and appends — a missing or malformed required field fails closed (non-zero exit, no line written) before it ever reaches disk. This verb replaces hand-authoring a JSONL line for the insights store.

Procedure

  1. Identify the record kind via --type: defect (an observed problem), defect-resolution (the fix outcome), improvement (a post-correction lesson — the record AGENTS.md § Behavior Rules requires when the operator course-corrects in flight; rationale in docs/governance/behavior-rules.md § Always #11), or discovery (a survey finding).

  2. Supply --scope (the surface or skill the record names) and --summary (a one-sentence record body). Both are required and fail closed when empty.

  3. Optionally attach --evidence <command-or-path> (repeatable — pass it once per witnessing command or file) and --next-action <text> (what changes structurally to prevent recurrence). Say whose words the record carries with --source operator|agent (default agent): pass operator only for the operator's own words; an agent's reading of them stays agent (operator ruling 2026-10-18). When the record replaces an earlier one, name it with --supersedes <ts>; a ts no record carries is refused before anything is written.

  4. Run the capture:

    uv run gz insights remember --type <defect|defect-resolution|improvement|discovery> \
      --scope <surface-or-skill> --summary "<one-sentence body>" \
      [--evidence <command-or-path> ...] [--next-action "<structural change>"] \
      [--source operator|agent] [--supersedes <ts>]
    
  5. The command fails closed (non-zero exit, no line written) when --type, --scope, or --summary is empty, or when --type is out of the InsightType enum — construction is what enforces the schema.

Validation

  • A new line is appended to .gzkit/insights/agent-insights.jsonl (the file/dir is created on first use).
  • The line's ts field is stamped with the current UTC instant automatically — no manual timestamp is ever required.
  • One insight_recorded event is appended to the ledger naming the record: its ts, a SHA-256 of the line, the source, and any supersedes. A recorded line edited by hand afterwards fails gz validate --insights-shape.

Before a recorded failure becomes a rule

A single failure stays an insight (maxim 13). To propose that a recurring failure become a rule, cite its records and run the recurrence check; propose the rule only on exit 0:

uv run gz insights recurrence <insight-ts> '#<N>' '#<M>'

You judge that the cited records share one class of failure; the verb checks only the count against data/recurrence_threshold.json and that every pair is a session lease apart. Manpage: docs/user/manpages/insights-recurrence.md.

Example

# Record a course-correction insight
uv run gz insights remember --type improvement --scope obpi-pipeline \
  --summary "governed author verb replaces hand-authored appends" \
  --next-action "delete the hand-authored append path"

# Record a defect with witnessing evidence
uv run gz insights remember --type defect --scope gzkit.insights \
  --summary "verb drifted from schema" \
  --evidence "uv run -m unittest tests.commands.test_insights_cmd"
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall