From 89a3312b51baa3f74211c27414583b9add1b802f Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 19 Apr 2026 14:40:34 -0500 Subject: feat: clean-room synthesis — brainstorm, memorize, root-cause-trace, five-whys MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four new skills synthesized from patterns in NeoLabHQ/context-engineering-kit (GPL-3.0). Clean-room approach: extracted rubrics from the originals (triggers, phases, hard cases, footguns, novel patterns), then wrote from scratch without referencing their prose. Ideas and methods aren't copyrightable; wording is. These skills are independent works. brainstorm Turn a vague idea into a validated design doc. Three phases: one-question-at-a-time dialogue, six-approach exploration (three conventional + three diverse tail samples for anti-convergence), chunked design presentation with per-chunk validation. Output: docs/design/.md. Hands off to arch-decide / arch-design / implementation. memorize Curate session insights into project CLAUDE.md under a dedicated "## Memorized Insights" section. Grow-and- refine per ACE (arXiv:2510.04618): atomic, evidence- backed, non-redundant bullets. Args: --dry-run, --max, --target, --section, --source. Flags cross-project patterns for promotion to ~/code/rulesets/claude-rules/. Clearly delineates from auto-memory (private) and formal rules (stable policy). root-cause-trace Backward-walk technique for debugging. Observe symptom → identify immediate cause → walk up the call chain → find original trigger → fix at source + defense-in- depth at each intermediate layer. Instrumentation guidance (stack capture before the dangerous op, not after; stderr not framework logger in tests); test- pollution bisection. Companion to /debug — /debug is broader; this is specifically the backward walk. five-whys Iterative why-questioning from symptom to process/ decision root cause. Five is a convention, not a quota — stop when a cause, if eliminated, would prevent every symptom in the chain. Handles branching (multiple contributing causes). Validates chains by walking back from root to symptom. Refuses to terminate at "human error" or "not enough budget" — those have deeper whys. Companion to root-cause-trace (that's for code execution; this is for process). Makefile SKILLS extended. make install symlinks all four into ~/.claude/skills/ alongside existing skills. Lint clean. --- memorize/SKILL.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 memorize/SKILL.md (limited to 'memorize/SKILL.md') diff --git a/memorize/SKILL.md b/memorize/SKILL.md new file mode 100644 index 0000000..f77540f --- /dev/null +++ b/memorize/SKILL.md @@ -0,0 +1,192 @@ +--- +name: memorize +description: Curate concrete, actionable insights into the project's `CLAUDE.md` so they survive across sessions and compound over time. Harvests recent-session learnings (patterns that worked, anti-patterns that bit, API gotchas, verification checks), filters against quality gates (atomic, evidence-backed, non-redundant, verifiable, safe), and writes into a dedicated `## Memorized Insights` section rather than scattering entries. Use after a productive session, a bug fix that revealed a non-obvious pattern, or an explicit review where you want learnings preserved. Supports `--dry-run` to preview, `--max=N` to cap output, `--target=` to write elsewhere, `--section=` to override the destination section. Flags insights that look cross-project and suggests promotion to `~/code/rulesets/claude-rules/` instead. Do NOT use for session wrap-up / progress summaries (not insights), for private personal context (auto-memory handles that, not a tracked file), or for rules that belong in a formal rules file (those go under `.claude/rules/`). Synthesis of Agentic Context Engineering (ACE, arXiv:2510.04618) — grow-and-refine without context collapse. +--- + +# Memorize + +Turn transient session insights into durable, actionable entries in the project's `CLAUDE.md`. The goal: each run of this skill should make the next session measurably better, without diluting what's already there. + +## When to Use + +- End of a productive session where you want concrete patterns preserved +- After a bug fix that revealed a non-obvious constraint or gotcha +- After a review where a pattern was identified as worth repeating (or avoiding) +- When you notice yourself re-deriving the same insight — it belongs written down + +## When NOT to Use + +- For a session wrap-up summary (that's narrative, not an insight) +- For personal/private context (auto-memory at `~/.claude/projects//memory/` captures that — see below) +- For formal project rules — those belong in `.claude/rules/*.md` +- When you have no specific, evidence-backed insight yet — skip rather than fabricate + +## Relationship to Other Memory Systems + +Three distinct systems, zero overlap: + +| System | Location | Scope | Purpose | +|---|---|---|---| +| **auto-memory** | `~/.claude/projects//memory/` | Private, per-working-directory | Session-bridging context about the user and project (feedback, user traits, project state). Written continuously by the agent. | +| **`/memorize` (this skill)** | Project `CLAUDE.md` | Public, tracked, per-project | Explicit, curated rules and patterns. Written deliberately by the user invocation. | +| **Formal rules** | `.claude/rules/*.md`, `~/code/rulesets/claude-rules/` | Public, tracked, per-project or global | Stable policy (style, conventions, verification). Authored once, rarely updated. | + +Use the right system for the right content. + +## Workflow + +Four phases. Each can be skipped if it has no content; none should be silently merged. + +### Phase 1 — Harvest + +Identify candidate insights from recent work. Look at: + +- The session transcript (or files referenced by `--source`) +- Recent commits and their messages +- Any `.architecture/evaluation-*.md` from `arch-evaluate` +- Reflection or critique outputs if they exist +- Anti-patterns you caught yourself falling into + +**Extract only:** + +- **Patterns that worked** — preferably with a minimum precondition and a worked example or reference +- **Anti-patterns that bit** — with the observable symptom and the reason +- **API / tool gotchas** — auth quirks, rate limits, idempotency, error codes +- **Verification items** — concrete checks that would catch regressions next time +- **Specific thresholds** — "pagination above 50 items" not "pagination when needed" + +**Exclude:** + +- Progress narrative ("today we shipped X") +- Personal preferences ("I like functional style") +- Vague aphorisms ("write good code") +- Unverified claims (if you can't cite code, docs, or repeated observation, skip) + +### Phase 2 — Filter (Grow-and-Refine) + +For each candidate insight, apply these gates. Fail any → drop the entry. + +- **Actionable.** A reader could apply this immediately. "Write good code" fails; "For dataset lookups under ~100 items, Object outperforms Map in V8" passes. +- **Specific.** Names a threshold, a file, a flow, a version, or a named tool. Generic insights are noise. +- **Evidence-backed.** Derived from code you just read, docs you just verified, or a pattern observed more than once. Speculation doesn't count. +- **Atomic.** One idea per bullet. If the insight has two distinct parts, it's two bullets. +- **Non-redundant.** Check existing `CLAUDE.md` content. If something similar exists, prefer merging or skipping over duplicating. If the new one is genuinely more specific and evidence-backed than the existing one, append it and mark the older one with `(candidate for consolidation)` — don't auto-delete prior user content. +- **Safe.** No secrets, tokens, private URLs, or PII. Nothing that would leak in a public commit. +- **Stable.** Prefer patterns that'll remain valid. If version-specific, say so. + +### Phase 3 — Write + +Write approved insights to a dedicated section of `CLAUDE.md`. Default section name: **`## Memorized Insights`**. Override with `--section=`. + +**Discipline:** + +- **One section only.** Don't scatter entries across CLAUDE.md. All memorized content in one place means future `/memorize` runs and human readers find it fast. +- **Create the section if absent.** Place it near the end of CLAUDE.md, before any footer links. +- **Preserve chronology within the section.** Newer entries appended; don't shuffle. +- **Include provenance.** Each entry gets a date and, where useful, a one-word source hint (`pattern:`, `gotcha:`, `threshold:`, `anti-pattern:`, `verify:`). + +**Entry format:** + +```markdown +- **.** (`` — YYYY-MM-DD) +``` + +Examples: + +```markdown +- **Pagination threshold.** Fetch endpoints returning >50 items must paginate; clients assume everything ≤50 is complete. (`threshold` — 2026-04-19) +- **Map vs Object for small lookups.** In V8, Object outperforms Map for <~100 keys; Map wins at 10k+. Use Object for hot config lookups. (`pattern` — 2026-04-19) +- **Never log `load-file-name` from batch-compile context.** Both `load-file-name` and `buffer-file-name` are nil during top-level evaluation; `file-name-directory nil` raises `stringp, nil`. (`gotcha` — 2026-04-19) +``` + +### Phase 4 — Validate + +After writing, check: + +- [ ] Every entry passed all Phase 2 gates +- [ ] Each entry is atomic (one idea) +- [ ] No near-duplicates were created +- [ ] The `## Memorized Insights` section is coherent — entries flow, categories aren't interleaved randomly + +If the validation surfaces a problem, fix before exiting. + +## Cross-Project Promotion + +Some insights apply to *all* the user's projects, not just this one. Examples: + +- "Always emit JSON with a stable key order for git diffs" +- "For TypeScript libraries, expose types via `package.json#exports`" + +When an insight reads as general rather than project-specific, the skill emits a **promotion hint** at the end of the run: + +``` +Promotion candidates: +- "JSON stable key order" — reads as general. Consider adding to: + ~/code/rulesets/claude-rules/style.md + (would apply to every project via global install) + +Keep as project-specific, promote, or drop? [k/p/d] +``` + +Promotion happens manually — the skill doesn't edit the rulesets repo automatically. The hint is a nudge to think about scope. + +## Arguments + +- **`--dry-run`** — show the proposed entries and where they'd be written; do not modify any files. +- **`--max=N`** — cap output to the top N insights by specificity + evidence. +- **`--target=`** — write to a different file. Defaults to `./CLAUDE.md`. Use e.g. `docs/learnings.md` if the project prefers a separate file. +- **`--section=`** — override the default `## Memorized Insights` section name. +- **`--source=`** — scope what gets harvested. Values: `last` (most recent message), `selection` (a user-highlighted region if supported), `chat:` (a specific past conversation), `commits:` (e.g., `commits:HEAD~10..`). Defaults to a reasonable window of recent session context. + +## Output + +On a real run (not `--dry-run`): + +1. Short summary — "added N entries to ``: X patterns, Y gotchas, Z thresholds." +2. Any promotion candidates flagged for global-rules consideration. +3. Confirmation of the file path modified. + +On `--dry-run`: + +1. Preview of each proposed entry with the section it would land in. +2. Flagged promotions. +3. Explicit confirmation nothing was written. + +## Anti-Patterns + +- **Summarizing the session instead of extracting insights.** "Today we refactored X" is narrative. "X's public API requires parameters in Y order due to Z" is an insight. +- **Writing entries without evidence.** If you can't point to code, docs, or multiple observations, the entry is speculation. +- **Overwriting prior content.** Mark conflicts for consolidation; don't auto-delete what the user wrote. +- **Scattering entries.** One section. Grep-able. Coherent. +- **Batch-writing 20 entries in one session.** If the session generated 20 real insights, many of them aren't. Filter harder. 3-5 genuine entries per run is typical. +- **Adding to `CLAUDE.md` when auto-memory is the right system.** Private user-context goes in auto-memory; public project rules go here; static policy goes in `.claude/rules/`. +- **Promoting too eagerly.** "This applies to all projects" is a strong claim. If you can't name three unrelated projects where the rule would fire, it's project-specific. + +## Review Checklist + +Before accepting the additions: + +- [ ] Each entry has a source hint and a date +- [ ] Each entry passes the atomic / specific / evidence-backed / non-redundant / safe / stable gates +- [ ] The `## Memorized Insights` section exists exactly once in the target +- [ ] Promotion candidates (if any) have been flagged, not silently promoted +- [ ] `--dry-run` was used at least once if the target file is under active template management (e.g. bundled CLAUDE.md from rulesets install) + +## Maintenance + +`CLAUDE.md` accumulates over time. Periodically: + +- **Consolidate.** Entries marked `(candidate for consolidation)` deserve a look. Often the older entry is superseded; sometimes it's a special case of the newer one. +- **Retire.** Entries about deprecated tools or obsolete versions should be removed explicitly (with a commit message noting the retirement). +- **Promote.** Re-scan for entries that have started firing across multiple projects — those belong in `~/code/rulesets/claude-rules/`. +- **Trim.** If the section grows past ~40 entries, either the project is complex enough to warrant splitting `CLAUDE.md` into multiple files, or the entries haven't been curated aggressively enough. + +## Theoretical Background + +The grow-and-refine / evidence-backed approach draws on Agentic Context Engineering (Zhang et al., *Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models*, arXiv:2510.04618). Key ideas borrowed: + +- **Generation → Reflection → Curation** as distinct phases, not a single compression step +- **Grow-and-refine** — accumulate granular knowledge rather than over-compressing to vague summaries +- **Avoiding context collapse** — resist the temptation to rewrite old entries into smoother prose; specificity is the value + +This skill implements the Curation phase. Reflection and Generation happen in the main conversation. -- cgit v1.2.3