<img width="1649" height="158" alt="Group 6 (1)" src="https://github.com/user-attachments/assets/93f0210f-c3ce-4035-91df-ec597e00a3ce" />

Intent is the new source code

Turn your AI development conversations into searchable, shareable knowledge.

Never lose a brilliant solution, code snippet, or architectural decision again. SpecStory captures, indexes, and makes searchable every interaction you have with AI coding assistants across all your projects and tools.

<p align="left"> <strong>Install SpecStory ──▶ </strong>&nbsp; <a href="https://specstory.com"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fspecstory.com%2Fapi%2Fbadge%3Fstat%3Dinstalls&style=flat-square" alt="Installs" style="vertical-align: middle;"></a> <a href="https://specstory.com"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fspecstory.com%2Fapi%2Fbadge%3Fstat%3DactiveUsers&style=flat-square" alt="Active Users" style="vertical-align: middle;"></a> <a href="https://specstory.com"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fspecstory.com%2Fapi%2Fbadge%3Fstat%3DsessionsSaved&style=flat-square" alt="Sessions Saved" style="vertical-align: middle;"></a> <a href="https://specstory.com"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fspecstory.com%2Fapi%2Fbadge%3Fstat%3DrulesGenerated&style=flat-square" alt="Rules Generated" style="vertical-align: middle;"></a> </p> <p align="left"> <strong>Contribute to OSS ──▶</strong>&nbsp; <a href="https://github.com/specstoryai/getspecstory/tree/main/specstory-cli"><img src="https://img.shields.io/badge/CLI-Open%20Source-brightgreen?style=flat-square" alt="CLI Open Source" style="vertical-align: middle;"></a> <a href="./lore"><img src="https://img.shields.io/badge/Lore-Forge%20Skills-brightgreen?style=flat-square" alt="Lore: forge skills from your sessions" style="vertical-align: middle;"></a> </p> <p align="left"> <strong>Connect with us ───▶</strong>&nbsp; <a href="https://twitter.com/specstoryai"><img src="https://img.shields.io/badge/X-000000?style=flat-square&logoColor=white" alt="X" style="vertical-align: middle;"></a> <a href="https://www.linkedin.com/company/specstory"><img src="https://img.shields.io/badge/LinkedIn-0077B5?style=flat-square&logo=linkedin&logoColor=white" alt="LinkedIn" style="vertical-align: middle;"></a> <a href="https://specstory.slack.com/join/shared_invite/zt-2vq0274ck-MYS39rgOpDSmgfE1IeK9gg#/shared-invite/email"><img src="https://img.shields.io/badge/Slack-4A154B?style=flat-square&logo=slack&logoColor=white" alt="Slack" style="vertical-align: middle;"></a> <a href="https://discord.gg/E47yQyEUd3"><img src="https://img.shields.io/badge/Discord-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" style="vertical-align: middle;"></a> <a href="https://www.youtube.com/@specstory"><img src="https://img.shields.io/badge/YouTube-FF0000?style=flat-square&logo=youtube&logoColor=white" alt="YouTube" style="vertical-align: middle;"></a> </p>

📜 Lore - Mine your saved sessions into evidence-backed agent skills, forged from how you actually work. Your sessions are your lore.

How It Works

AI Coding Tools              Local First                  Cloud Platform
─────────────────           ─────────────                ─────────────────
                                                          (Login Required)
Cursor IDE         ┐
Copilot IDE        │
Claude Code CLI    │
Cursor CLI         │
Codex CLI          ├──────►  .specstory/history/  ──────►  cloud.specstory.com
Droid CLI          │          (Auto-Saved Locally)        (Search, Ask & Share)
Gemini CLI         │
DeepSeek TUI       │
Antigravity CLI    │
Muse Code          ┘

Workflow

1. Capture - Extensions save every AI interaction locally to .specstory/history/
2. Process - Run /lore to mine your history into reusable, evidence-backed agent skills
3. Sync (Optional) - Only if logged in, sessions sync to cloud
4. Search - Find conversations locally or across all projects in cloud
5. Share - Export and share specific solutions with your team

Supported Development Tools

SpecStory integrates seamlessly with your favorite AI coding tools, automatically saving all conversations locally to .specstory/history/ in your project. Everything is local-first - your data stays on your machine unless you choose to sync to the cloud.

Installation

Product	Type	Source	Supported Agent	Min Version	Installation	Changelog
Cursor Extension	IDE	Closed	Cursor AI	v0.43.6+	Search "SpecStory" in Extensions (Cmd/Ctrl+Shift+X) → Install	📋 View
VSC Copilot Extension	IDE	Closed	GitHub Copilot	v1.300.0+	Search "SpecStory" in Extensions (Cmd/Ctrl+Shift+X) → Install	📋 View
SpecStory CLI	CLI	Open	Claude Code	v1.0.27+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
SpecStory CLI	CLI	Open	Codex CLI	v0.42.0+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
SpecStory CLI	CLI	Open	Cursor CLI	v2025.09.18+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
SpecStory CLI	CLI	Open	Droid CLI	v0.56.3+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
SpecStory CLI	CLI	Open	Gemini CLI	0.15.1+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
SpecStory CLI	CLI	Open	DeepSeek TUI	0.8.39+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
SpecStory CLI	CLI	Open	Antigravity CLI	v1.1.5+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
SpecStory CLI	CLI	Open	Muse Code	0.1.0+	brew tap specstoryai/tap<br/>brew install specstory	📋 View
Lore 📜	Skill	Open	Any Agent Skills	Node 22.5+	npx skills add specstoryai/getspecstory --skill lore	📋 View

[!NOTE] For Cursor users: Install from within Cursor, not from the Visual Studio Marketplace website. Learn why

CLI Tools

One installation works with all CLI tools - Claude Code, Cursor CLI, Codex, Droid, DeepSeek, and Antigravity:

# Check which agents are installed
specstory check

# Launch your preferred agent with auto-save
specstory run claude       # Launch Claude Code
specstory run cursor       # Launch Cursor CLI
specstory run codex        # Launch Codex CLI
specstory run droid        # Launch Droid CLI
specstory run gemini       # Launch Gemini CLI
specstory run deepseek     # Launch DeepSeek TUI
specstory run antigravity  # Launch Antigravity CLI
specstory run muse         # Launch Muse Code
specstory run           # Launch default agent

All sessions automatically save to .specstory/history/ in your current project.

[!TIP] The SpecStory CLI acts as a wrapper that enhances any of these terminal agents with automatic session saving. You only need the respective agent installed (e.g., Claude Code) for SpecStory to work with it.

Lore 📜

Lore turns the sessions SpecStory saves into agent skills forged from how you actually work. Your sessions are your lore.

The Problem We Solve

• Repeated Yourself Again: You re-explain the same workflows, conventions, and fixes to your agent every session
• Skills From Guesswork: Hand-written agent skills describe how you think you work, not how you demonstrably do

The Solution

Lore mines your .specstory/history into evidence - what you actually ran, what worked, and the judgment you apply without noticing - and forges the skills you approve into every agent on your machine.

Install:

npx skills add specstoryai/getspecstory --skill lore

Then invoke it - /lore in Claude Code, $lore in Codex, or just ask ("mine my lore") in Gemini CLI and others:

/lore

Get Started with Lore →

SpecStory Cloud ☁️

SpecStory Cloud transforms your local AI conversations into a powerful, centralized knowledge system.

The Problem We Solve

• Lost Context: Critical decisions and solutions scattered across machines and projects
• No Global Search: Finding that perfect solution from last month is impossible
• Fragile Sharing: Passing around Markdown files doesn't scale

The Solution

SpecStory Cloud creates your personal AI coding knowledge base:

• 🔍 Search Everywhere: Full-text search across all your projects via web interface. RAG coming soon.
• 🎯 Explicit Opt-In: Nothing syncs to cloud without sign-up and login first
• 📚 Organized by Project: Automatic categorization by repository and time
• 🚀 API Access: Programmatic sync and search for automation
• 👥 Team Features: Coming soon - share knowledge across your organization

Get Started with SpecStory Cloud →

How to Sync to Cloud

Method	One-Time Setup	Live Sessions	Past Sessions
SpecStory CLI	specstory login	Auto-pushed when using specstory run while logged in	Use specstory sync to push existing local sessions
Cursor Extension	Command Palette → "SpecStory: Open Cloud Sync Configuration"	Configure auto-sync in settings	Use sync command from Command Palette
VSCode Extension	Command Palette → "SpecStory: Open Cloud Sync Configuration"	Configure auto-sync in settings	Use sync command from Command Palette

[!IMPORTANT] Local-First & Private by Default: All sessions are saved locally to .specstory/history/. Nothing is ever sent to the cloud unless you explicitly login with. Even after logging in, you can control what gets synced.

Documentation & Support

• 📚 Full Documentation - Complete guides and Cloud API reference
• 📜 Lore - Forge your .specstory/history into installable agent skills, with evidence and outcomes
• 🐛 Report Issues - We actively monitor and respond
• 📖 Contribute to Docs - PRs welcome!

Reviews & Feedback

Love SpecStory? Help others discover their AI coding memory upgrade by leaving a review! 🧠

Star History

---

lore

---

name: lore description: SpecStory Lore - mine your SpecStory coding histories (any agent - Claude Code, Codex, Cursor, Gemini, and more) into a persistent corpus, surface your reproducible workflows with corroborated evidence, and interactively forge the chosen ones into skills installed across all your agent harnesses. Use when the user wants to turn past AI coding sessions into reusable skills, asks "what could I make into a skill", "mine my lore", "forge skills from my history", or points at a .specstory/history directory. argument-hint: "Enter = guided setup · or plain English, e.g. 'last 30 days, just show candidates'" allowed-tools: Bash, Read, Write, AskUserQuestion license: Apache-2.0 hooks: PreToolUse: - matcher: "ExitPlanMode" hooks: - type: command command: "node "${CLAUDE_SKILL_DIR}/scripts/hooks/validate-plan.mjs"" metadata: author: Greg Ceccarelli version: "3.9.0"

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 trigger.

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:

• Multi-author candidate = a TEAM practice, the strongest forge signal of all - propose it at project scope (committed .claude/skills) so the whole team benefits.
• 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 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.
• Privacy: teammate names may appear in team-scoped (committed) skills; scrub them from personal-scope skills.

Note on the evidence: every command candidate comes from an actually-executed shell <tool-use> block (detected by the provider-set data-tool-type="shell" attribute, so it works for Bash, Shell, run_shell_command, 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 <summary>) 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):

```zsh
find . -type d -path '*/.specstory/history' -not -path '*/node_modules/*' 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" → run status and render it verbatim (LAW 2), nothing else · "Reset my lore" → confirm, then reset.

This is a navigation question, not a candidate decision - LAW 1 does not apply to it. After the answers, echo the resolved interpretation in one line (per Step 0.5) and run. If the user typed ANY arguments, skip this step entirely and interpret them via Step 0.5.

Step 0.5 - Interpret the user's input

Map what the user typed to engine flags / process modes. If they gave nothing, Step 0.25 already collected the choices.

User says	Do
a path, "this project", nothing	--dir <path> (default .specstory/history); if nested histories exist, --scan .
"across my projects in ~/code", "compare A and B"	--projects <parent> or repeated --dir (cross-project mode)
"find all histories in here", monorepo with sub-package histories	--scan <root> (any depth, root's own history included)
"last 30 days", "since April"	--days N
"only the frequent ones", "did it 10+ times"	raise --min-sessions N
"just runbooks", "only command procedures"	--kind cmd (or runbook for cmd+task+corr)
"only how I work", "just meta-skills"	--kind meta
"about supabase", "migration skills", "focus on X"	--filter <substring>
"just show me candidates", "don't forge", "dry run"	run engine + synthesize (Steps 1–2b), then STOP - skip curate/forge
"status", "what have you done", "what's in my lore"	status - render the pass-through view verbatim
"what skills do I have", "show my skills", "list my forged skills"	skills - the installed-skills inventory (lore-forged with registry health + every other skill found in the harness dirs, with what each does); render verbatim (LAW 2)
"show me the last plan", "recall the candidates", "pick up where we left off"	plan last - re-renders the most recent saved plan against the current corpus; continue at Step 3 curation (no re-mining, no re-judging)
"reset my lore", "start fresh", "wipe everything"	reset (destructive: deletes the corpus, dossier cache, and forged registry - CONFIRM with the user first; add --and-skills only if they explicitly want forged skill files removed too)
"forge them all", "skip the questions"	still confirm scope once, but you may batch - do not silently write without any confirmation

Echo back the resolved interpretation in one line before running (e.g. "Mining ~/code cross-project, last 60 days, command runbooks about supabase").

Step 1 - Index, then report (two engine commands)

The engine keeps the user's lore at ~/.specstory/lore.db (override with --db). It segments every session into beats (intent → agent method → outcome, where the outcome label comes from the user's NEXT reply: approval = success, steering correction = corrected). Indexing is incremental - unchanged sessions are skipped, so re-running is cheap. Transcripts from ALL agents accumulate into the same lore; each session is tagged with its agent (claude-code, codex-cli, cursor-cli, ...).

# 1. index (repeat --dir per project, or --projects <parent> to scan many repos)
node "<skill-dir>/scripts/mine-skills.mjs" index --dir <history-dir>
node "<skill-dir>/scripts/mine-skills.mjs" index --projects <parent-dir-of-repos>

# 2. report candidates (filters: --days, --min-sessions, --top, --kind cmd,task,meta,corr, --filter <substr>)
node "<skill-dir>/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 and thus a new git_id). Run prune if the user has deleted or reorganized histories.

Step 2 - Synthesize candidate skills

From the evidence block, produce a shortlist of real skill proposals. For each kept candidate:

• name - a kebab verb-phrase (e.g. verify-go-changes, comprehensive-commit, fix-git-divergence).
• description (the trigger) - a one-line "Use when…" matched to how the behavior actually shows up in the evidence quotes. This is the most important field; it is what makes the skill discoverable.
• procedure - the steps, taken from the user's real command sequence or task shape. Do not invent steps; ground them in the evidence. Open the cited path:line refs (read the file at that span) if you need to confirm the exact commands before writing them into a skill.
• kind - runbook (a command procedure / task type) or meta-skill (a way of working).
• scope - personal (canonical ~/.agents/skills, fanned out to all harnesses) or project (<repo>/.claude/skills or the repo's equivalent, committed for the team).

Discard generic and weak candidates explicitly; tell the user what you dropped and why.

Skill-level idempotency - consult the registry first. Lore remembers what it has already forged and what the user has declined. Before proposing anything, run:

node "<skill-dir>/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 engine finds recurrence of surface forms - it does not understand meaning, so a high count can be a coincidence (unrelated commands that happen to sit adjacent) or a parsing artifact. Before forging, confirm each shortlisted candidate is a TRUE pattern using corroboration, not just its score:

1. Start from CORROBORATED. The engine already computed the strongest truth signal - intent × procedure co-occurring in the same beats, with outcome rates. A corroborated pair with a healthy success rate needs only a light read; a single-channel runbook or intent needs more scrutiny.
2. Re-open the evidence. Each evidence line is an beat (path:line [outcome] intent cmds). Open 1–2 spans (grep/sed the file at that line range; never the whole file) and confirm the arc is coherent: the commands serve that intent, the outcome label is plausible, it is one procedure rather than accidental neighbors.
3. Weigh outcomes honestly. Outcome labels are conservative - most beats are neutral because the next prompt is a new task. Treat ✗ corrected as a strong negative signal; treat a few ✓ as suggestive, not proof (small denominators).
4. Portability & distinctiveness (already scored): recurring across projects, or built from project-specific tooling, beats universal-command ubiquity.
5. Refute the cheap explanation. Would a skeptic say this is tool noise, one busy afternoon, or the agent flailing? If you cannot answer with evidence, drop it.

Only candidates that survive this check proceed to curation. This is the same discipline the 25-patterns extraction used (adversarial verification against real transcripts), applied to a handful of finalists so you never read whole transcripts - only the evidence behind the candidates that already cleared the bar.

Step 2b′ - Theme sweep: mine the LATENT expertise (semantic channel)

Command patterns are only the visible lore. The deeper skills - how the user reviews, decides, directs the model, diagnoses - live in conversational and read-only beats that form no command cluster at all (in some corpora that is 95%+ of beats). The theme sweep is a standard phase of every full-pipeline run, not an optional extra. Skip it ONLY when the user explicitly narrowed to command patterns (--kind cmd/runbook) or this corpus's saved themes are still fresh (theme render shows "evidence unchanged" on its cards). A run that presents only command-pattern candidates from a conversation-heavy corpus has mined the shallow 5% and called it the user's lore.

# cached themes first - sweeps are once-per-corpus-state, not once-per-run
node "<skill-dir>/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: "<skill-dir>/scripts/theme-sweep.workflow.js",
#             args: {skillDir, db, project: "<name>", sample: 30}})
# Other harnesses: spawn one subagent per lens with the same briefs, sampling via:
node "<skill-dir>/scripts/mine-skills.mjs" beats --project <name> --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 themes exist, propose the strongest of them alongside the command clusters - never present a command-only slate. The goal - and say this in the dossier - is latent expertise: a practice the user operates consistently but has never named. The forged skill should make them say "huh, I do do that." Register theme forges and declines by theme id (forged add/decline --cluster "<theme-id>" - the kind is inferred); the registry then drift-checks them by member-beat fingerprints like any cluster.

Expand each kept theme from anecdote to measurement (snowball). A verified theme cites the 4-8 beats a miner happened to read; on a large corpus the practice usually occurs in far more. The engine finds candidates deterministically (discriminating vocabulary from member intents, scored corpus-wide - no transcript reading):

node "<skill-dir>/scripts/mine-skills.mjs" theme expand --key <id> --max 40   # scored candidates
node "<skill-dir>/scripts/mine-skills.mjs" beats --keys "<k1>,<k2>,..."      # spans for the shortlist
node "<skill-dir>/scripts/mine-skills.mjs" theme grow --key <id> --keys "<confirmed,...>"

Verify candidates BEFORE growing - read the spans (subagents fine, batches of ~15) and confirm each genuinely exhibits the practice; lexical score is a lead, not membership. After growth the theme's card (theme render) shows prevalence ("N beats") and outcome lift - the practice's success rate vs the corpus baseline. Lead with the lift at curation: "you do this" is interesting, "when you do this it ends in approval 17 points more often" is a reason to forge.

Step 2c - Deep-mine the top clusters (Phase C)

For the top ~6 corroborated clusters that survived Step 2b - and when fewer than 3 corroborated clusters exist (common on conversational or legacy corpora where intent signatures are noisy), fall back to the top RUNBOOK clusters by sessions instead (--gram "<gram>" selectors work everywhere --corr does). A 23-session command loop with no clean intent pairing still deserves deep-mining - go beyond sampling: have a dedicated agent read EVERY beat in the cluster (especially the corrected ones) and produce a full dossier - canonical steps + variations, the verification moves actually used, failure modes with recoveries, and which parameters vary. The engine does the heavy prep:

# exact spans for one cluster, all corrected beats included first, with a content fingerprint
node "<skill-dir>/scripts/mine-skills.mjs" beats --corr "<intent_sig> × <gram>" --max 25

Check the cache first - deep-mining is once-per-cluster, not once-per-run:

node "<skill-dir>/scripts/mine-skills.mjs" dossier get --key "<cluster>"   # compare its fingerprint
# ... after mining: write dossier JSON to a tmp file, then
node "<skill-dir>/scripts/mine-skills.mjs" dossier put --key "<cluster>" --fingerprint "<fp>" --file <tmp>

If the cached fingerprint matches the current beats fingerprint, reuse it and skip mining.

**Parallelize with YOUR harness's subagent mecha

…