lore

# 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 <project> 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 (`### <name> …`, 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:

- **Keep it** when the procedure is distinctive and specific to how this user/project works
  (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).
- **Discard it** when it is generic to all coding and carries no project-specific procedure
  (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 trig