tvproductions/gzkit / .agents/skills/gz-insights-remember
gz-insights-remember
VerifiedUse 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
-
Identify the record kind via
--type:defect(an observed problem),defect-resolution(the fix outcome),improvement(a post-correction lesson — the recordAGENTS.md§ Behavior Rules requires when the operator course-corrects in flight; rationale indocs/governance/behavior-rules.md§ Always #11), ordiscovery(a survey finding). -
Supply
--scope(the surface or skill the record names) and--summary(a one-sentence record body). Both are required and fail closed when empty. -
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(defaultagent): passoperatoronly for the operator's own words; an agent's reading of them staysagent(operator ruling 2026-10-18). When the record replaces an earlier one, name it with--supersedes <ts>; atsno record carries is refused before anything is written. -
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>] -
The command fails closed (non-zero exit, no line written) when
--type,--scope, or--summaryis empty, or when--typeis out of theInsightTypeenum — 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
tsfield is stamped with the current UTC instant automatically — no manual timestamp is ever required. - One
insight_recordedevent is appended to the ledger naming the record: itsts, a SHA-256 of the line, thesource, and anysupersedes. A recorded line edited by hand afterwards failsgz 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"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |