lore skill

Lore

Your sessions are your lore. This skill turns a user's real coding history into installed skills. A deterministic engine (scripts/mine-skills.mjs) parses their SpecStory transcripts - from every agent SpecStory captures (Claude Code, Codex CLI, Cursor CLI, Gemini CLI, Factory Droid, DeepSeek, Antigravity, ...) - into a persistent corpus of beats, and returns corroborated candidates. You - the calling agent, whichever harness you are - supply all judgment: name them, discard the generic ones, and interactively forge the good ones into SKILL.md packages grounded in the user's own commands.

The engine does the retrieval and counting; you do the synthesis. Do not try to read raw transcripts yourself - they can be hundreds of thousands of lines. Run the engine and work from its output.

This skill is harness-portable (agentskills.io format). Where it names a specific tool (e.g. AskUserQuestion), treat that as "use your harness's equivalent; fall back to plain chat."

Voice: when narrating to the user, talk about mining their lore and skill candidates - e.g. "I'll mine your lore here in for skill candidates." Reserve the word forge for the final act only: creating the skills the user selected (Step 4). Never describe mining, judging, or candidates as "forge-…" anything.

OUTPUT CONTRACT - three LAWS, read before emitting anything to the user

Named failure mode #1 (2026-06-09, BearClaude run): the agent indexed, deep-mined four skills, then jumped straight to AskUserQuestion with bare option labels - ZERO dossiers rendered in chat. The user declined every question because they had nothing to judge by. The entire mining run was wasted.

Named failure mode #2 (2026-06-09, BearClaude run, SAME DAY, fresh session, LAWs in effect): the agent narrated phases correctly, did verification reads, then asked again with NO dossier message - its last message before the question was process narration ("CodeMirrorBundle is alive in today's repo…") - and the question text falsely claimed "dossiers above". Lesson: a felt self-check is not a check. Compliance must be MECHANICAL: the sentinel line below is the check, not your impression.

Named failure mode #3 (2026-06-10, teammate's machine, Opus 4.8, plan-mode path): the agent DID use plan-mode curation but presented a THIN plan - skill names and skip reasons with the dossiers summarized away - so the user approved a forge they never saw the evidence for. The plan UI makes skipping the display step impossible, not skipping the content. Lesson: the plan body must BE the engine's plan render artifact (Step 3), which embeds every card verbatim and ends with the LAW 1 sentinel. In Claude Code this is now HOOK-ENFORCED: a PreToolUse hook in this skill's frontmatter denies any ExitPlanMode whose plan is not that artifact.

LAW 1 - DOSSIERS BEFORE CANDIDATE QUESTIONS, PROVEN BY SENTINEL. This law governs candidate decisions - any prompt where the user chooses which skills to forge, skip, or update. (Navigation questions like the Step 0.25 guided start, or scope confirmations, are exempt - they decide nothing about candidates.) Before any candidate prompt you must emit one chat message that contains a full dossier block (### …, per Step 3) for EVERY candidate, and that message must END with this exact line:

=== dossiers above: N ===

where N equals the number of candidates you are about to offer. At the moment of asking, the check is mechanical: "Does a prior message of mine end with === dossiers above: N === and does N match my option count?" No sentinel → you have not rendered dossiers, whatever you remember - STOP and write them. Process narration between tool calls does NOT count; interim notes do NOT count.

The strongest form of LAW 1 is plan-style curation (Claude Code, see Step 3): present the dossiers AS the plan via ExitPlanMode - then showing the evidence and asking for the decision are the same act, and skipping the display is structurally impossible. But the plan only enforces that something is shown, not what (failure mode #3): the plan body must embed the engine-rendered dossier cards verbatim and end with the sentinel, same mechanical check as chat. The sentinel path alone is the fallback for harnesses without plan mode.

LAW 2 - RENDER THE ENGINE'S VISUALS VERBATIM, IN A REAL MESSAGE. After the report, you must emit a user-facing mining summary MESSAGE (tool output alone does not count - the user should not need to expand collapsed tool results). It opens with the engine's 📜 lore · … badge line and ends with the <!-- PASS-THROUGH FOOTER --> block, both verbatim. The same rule covers every PASS-THROUGH block the engine emits (STATUS, THEMES, DOSSIERS). Going tool → tool → question with no synthesis message in between is failure mode #2.

LAW 3 - NARRATE PHASES. Before every long-running engine or deep-mine call, emit one short status line so the window always shows what is happening: 📜 indexing BearClaude (253 sessions)…, 📜 deep-mining 4 clusters (this runs subagents; a few minutes)…, 📜 checking the forged-skill registry…. Never leave the user staring at a silent tool call.

What makes a candidate skill-worthy

A reproducible skill is a behavior that recurs, is regular, and has a clear trigger. The engine scores for recurrence/span/recency/specificity/outcomes; you apply the judgment it cannot:

(e.g. supabase link → supabase db → supabase migration, gh run watch CI-watching, "write a comprehensive commit", "fix git divergence against origin/main", a read-only diagnosis).

• Keep it when the procedure is distinctive and specific to how this user/project works

(e.g. bare git status → git diff, a lone "yes"/"do 1,2,3" confirmation). High session counts alone do not make a skill - ubiquity is not a trigger.

• Discard it when it is generic to all coding and carries no project-specific procedure

In cross-project mode the engine splits candidates into PORTABLE (recurs across ≥2 projects) and PROJECT-SPECIFIC (one project). Portability is the strongest signal of a real transferable skill: forge PORTABLE ones to the personal canonical dir and PROJECT-SPECIFIC ones into that repo.

Authorship (shared repos): committed histories carry their session owner - the engine attributes every session (git add-author > home-dir sniff > machine user) and candidates show 👥 N authors when several people exhibit the behavior. Use it:

project scope (committed .claude/skills) so the whole team benefits.

• Multi-author candidate = a TEAM practice, the strongest forge signal of all - propose it at

recommend team scope or checking with them before forging it as the user's own practice. Never present a teammate's workflow as the user's.

• Single-author, and it's the current user = personal candidate, personal scope.
• Single-author, a TEAMMATE's = say so plainly in the dossier ("mined from Jake's sessions") and

personal-scope skills.

• Privacy: teammate names may appear in team-scoped (committed) skills; scrub them from

Note on the evidence: every command candidate comes from an actually-executed shell block (detected by the provider-set data-tool-type="shell" attribute, so it works for Bash, Shell, runshellcommand, exec_command, and every other provider's runner). It is real agent activity, not a pasted example. Single-line commands (inline backtick or in the tool ) and multi-line

## Process

### Step 0 - Locate the history directory(ies)

Default to `.specstory/history` in the current project - but **check for nested histories first**
(monorepos keep them in sub-packages too):

find . -type d -path '/.specstory/history' -not -path '/nodemodules/' 2>/dev/null | head

If more than one shows up, use `--scan .` (any-depth discovery, includes the root's own history).
For **cross-project trends** across sibling repos, pass several `--dir` flags, one
`--projects <parent>`, or `--scan <parent>`. If no history exists anywhere, tell them SpecStory
records sessions and stop.

### Step 0.25 - Guided start (when invoked with NO arguments)

A bare `/lore` means the user wants to be walked through it. Ask ONE structured question round
(`AskUserQuestion` with three questions; plain numbered lists on harnesses without it), then proceed -
do not make them learn the argument grammar:

1. **Scope** (header "Scope"): "This project (Recommended)" → cwd history, auto-`--scan .` if nested
   histories exist · "All my repos under a folder" → ask which parent, then `--scan <parent>` ·
   "Just the existing corpus" → skip indexing, report on `~/.specstory/lore.db` directly.
2. **Window** (header "Window"): "All time (Recommended)" · "Last 30 days" → `--days 30` ·
   "Last 90 days" → `--days 90`.
3. **Goal** (header "Goal"): "Find & forge skills (Recommended)" → full pipeline ·
   "Just show me candidates" → stop after dossiers, no forging · "Status / what has Lore done"

1. index (repeat --dir per project, or --projects to scan many repos)

node "/scripts/mine-skills.mjs" index --dir node "/scripts/mine-skills.mjs" index --projects

2. report candidates (filters: --days, --min-sessions, --top, --kind cmd,task,meta,corr, --filter )

node "/scripts/mine-skills.mjs" report --min-sessions 3 --top 10

(Legacy one-shot `--dir` without a subcommand does index + report together.) The report is wrapped in
`<!-- EVIDENCE FOR SYNTHESIS -->` markers - raw evidence for you, not the user (`--emit=json` for
structured output). It has four sections; **read CORROBORATED first**:

- **CORROBORATED** - intent × procedure pairs co-occurring in the *same beats*, with outcome rates.
  These are pre-verified deep-skill seeds: the user *asked* for X and the agent *did* Y, repeatedly.
- **RUNBOOKS** - executed command procedures (single-channel).
- **INTENTS** - recurring prompt task-types (single-channel).
- **META-SKILLS** - ways-of-working detectors.

Each evidence line carries `path:line [outcome] intent=… cmds=…` - an beat you can open directly.

**Re-running is safe and expected.** Indexing is idempotent: unchanged sessions are skipped
(fingerprint = size + mtime + parser version); new sessions are appended; grown/edited sessions are
replaced whole; engine upgrades re-parse the whole corpus automatically (one-time). `--force`
re-indexes everything; `prune` drops sessions whose transcript files no longer exist and flags
duplicate project identities (e.g. a repo that later gained a git remote a

node "/scripts/mine-skills.mjs" forged check --emit json

and obey each row's `recommendation`:

- `up-to-date` - the forged skill's cluster is unchanged: exclude it from candidates entirely.
- `update: N new corrected beat(s), sessions A→B` - the evidence grew materially since forging:
  propose an **update to the existing skill** (deep-mine the cluster, diff the new failure modes /
  steps into the installed SKILL.md), never a duplicate.
- `update-carefully (user hand-edited the file)` - same, but present the diff and let the user apply;
  do not overwrite their edits.
- `suppress: user declined...` - do NOT re-propose; mention it only in the discard list ("declined
  previously, evidence unchanged").
- `re-engage: evidence grew materially since the user declined` - you MAY re-propose, saying exactly
  what changed since they said no.
- `orphaned` - the skill file was deleted; offer to re-forge or forget it.

Also `ls ~/.agents/skills/` for skills NOT authored by Lore (no registry row) - match those by name
and skip duplicates. Re-running /lore today, tomorrow, or next month must never produce duplicate
skills; it should produce **updates** as the lore grows.

### Step 2b - Verify each candidate against the source (the truth check)

The

cached themes first - sweeps are once-per-corpus-state, not once-per-run

node "/scripts/mine-skills.mjs" theme list # or theme render for the human-readable cards

Claude Code: run the bundled workflow (six thematic lenses + adversarial verification)

Workflow({scriptPath: "/scripts/theme-sweep.workflow.js",

args: {skillDir, db, project: "", sample: 30}})

Other harnesses: spawn one subagent per lens with the same briefs, sampling via:

node "/scripts/mine-skills.mjs" beats --project --shape conversation --max 30 --min-intent-len 40

Save every surviving theme (`theme put` with its stable member keys), then treat each theme exactly
like a corroborated cluster: `beats --theme <id>` exports its spans, deep-mine produces its
dossier (cache key `theme:<id>`, and the deep-mine workflow accepts `kind: "theme"` clusters), and
it joins curation with the others. **The curation slate must be MIXED: when verified