legreffier-explore

name	legreffier-explore
description	Systematic diary exploration: discover tags, entry distribution, coverage gaps, agent mistakes, and compile recipes. Use when onboarding to a new diary or journal, before consolidation, to analyze or review diary log entries, or when asked to "explore the diary", "diary overview", or "what's in the diary".

LeGreffier Explore Skill

Systematically explore a diary to understand what's in it, find patterns and gaps, and recommend compile recipes. This is the discovery step — run it before consolidation, before designing compile recipes, or when onboarding to a diary you haven't worked with before.

Agent name resolution

Follow the same resolution order as the main legreffier skill (env var → argument → gitconfig → single .moltnet/ subdirectory → ask user). Store as AGENT_NAME. All MCP calls use mcp__<AGENT_NAME>__*.

Prerequisites

• LeGreffier MCP tools available (entries_list, entries_search, diaries_list, diaries_get)
• Agent identity active (mcp__<AGENT_NAME>__moltnet_whoami)
• Diary resolved (match repo name via diaries_list, or use MOLTNET_DIARY_ID env var)

Transport detection

After resolving AGENT_NAME and DIARY_ID, detect available transport:

1. If MCP tools are available (moltnet_whoami responds): use MCP for all operations.
2. If MCP unavailable or errors with "Auth required" / connection failures: use CLI via $MOLTNET_CLI for all operations.
3. Do not mix transports within a session. Pick one at activation and stick with it.

CLI credentials: .moltnet/<AGENT_NAME>/moltnet.json CLI global flags: --credentials ".moltnet/<AGENT_NAME>/moltnet.json"

CLI equivalents

MCP Tool	CLI Command
entries_list	moltnet entry list --diary-id <uuid> [--tags "..." --entry-type <type> --limit <n>]
entries_search	moltnet entry search --query "..." [--diary-id <uuid>] [--tags "..."] [--entry-types "..."]
diary_tags	moltnet diary tags <diary-id>
diaries_compile	moltnet diary compile <diary-id> --token-budget <n> [--task-prompt "..."]
packs_create	moltnet pack create --diary-id <uuid> --entries '<json>'
packs_render_preview	moltnet pack render --preview <pack-uuid> [--out context-pack.md]
packs_render	moltnet pack render <pack-uuid> [--out rendered-pack.md]

When to trigger

• First time working with a diary or journal (onboarding)
• Before designing compile recipes for a new task domain
• After a batch of work (50+ new entries) to check diary health
• When compile packs feel noisy or incomplete
• When asked to "explore the diary", "diary analysis", "review diary", or "what's in the diary"

Operator preflight

Before creating any scratch artifact, propose a few exploration directions to the operator and let them steer the search space.

The first output should be a short operator-facing preflight, not a scratch file. Offer 2-4 concrete directions such as:

• incident-first: focus on mistakes, fixes, and preventive context
• decision-first: focus on architectural constraints and stable rules
• subsystem-first: focus on one tag namespace or subsystem
• retrieval-first: focus on what should go into a manual context pack

Then ask the operator to control the search scope. Prefer explicit operator input over inference when the interface allows it. Capture at least:

• target objective
• chosen direction
• preferred tags or tag namespaces
• excluded tags
• entry types to emphasize
• search terms or recurring questions to chase
• optional time window

If the operator does not care or does not answer, proceed with a broad exploration and record that the defaults were inferred. If they do answer, the scratch output must record their choices so later packs_create work stays traceable.

Exploration phases

Run phases in order. Each phase builds on the previous one's findings. Use subagents for phases 2-4 to keep the primary context clean.

Phase 1: Inventory

Map what's in the diary using diary_tags (fast) and a single entries_list pass (for importance distribution and temporal range).

See references/discovery-to-pack-method.md Phase A for the full tag landscape mapping procedure with prefix filters.

Step 1a — Tag landscape (use diary_tags):

diary_tags({ diary_id })                          → full tag list
diary_tags({ diary_id, min_count: 3 })            → filter noise
diary_tags({ diary_id, prefix: "scope:" })        → domain scopes
diary_tags({ diary_id, prefix: "source:" })       → content origin
// repeat for each discovered prefix

Step 1b — Tag x entry type cross-referencing (see references/discovery-to-pack-method.md Phase B):

diary_tags({ diary_id, entry_types: ["semantic"], min_count: 2 })
diary_tags({ diary_id, entry_types: ["episodic"], min_count: 2 })
diary_tags({ diary_id, entry_types: ["procedural"], prefix: "scope:", min_count: 5 })
diary_tags({ diary_id, entry_types: ["reflection"] })

Build an intersection matrix to identify pack-worthy combinations. Rule of thumb: 5+ entries to be useful, 10+ to be robust.

Step 1c — Entry-level stats (use entries_list):

entries_list({ diary_id, limit: 50, offset: 0 })
// paginate to cover all entries

Compute from entries:

1. Entry type counts: count per entryType value
2. Importance distribution: histogram of importance values (1-10)
3. Temporal range: earliest and most recent entry dates

Output: inventory table + tag namespace tree + intersection matrix (see Output format).

Phase 2: Agent mistakes (episodic analysis)

Find incidents that document mistakes agents made — candidates for Task Harvest eval tasks and entry relations.

entries_list({ diary_id, tags: ["incident"], limit: 20 })
entries_search({ diary_id, query: "bug fix workaround error failed",
                 entry_types: ["episodic"], limit: 15 })

If no incident-tagged entries exist, fall back to:

entries_search({ diary_id, query: "what happened root cause fix applied",
                 entry_types: ["episodic"], limit: 20 })

For each episodic entry, extract:

Field	What to capture
What went wrong	The mistake or failure
Root cause	Why it happened
Fix applied	What resolved it
Preventive context	What knowledge would have prevented it
Subsystem	Infer from tags or content
Severity	Critical / High / Medium / Low

Group by subsystem. Highest-severity incidents with clear preventive context are the best Task Harvest candidates.

Phase 3: Commit patterns (procedural analysis)

Understand how agents commit — scope distribution, risk levels, branch patterns.

entries_list({ diary_id, limit: 30,
               tags: [<most common procedural tag from Phase 1>] })

If no obvious procedural tag exists, use:

entries_search({ diary_id, query: "commit",
                 entry_types: ["procedural"], limit: 30 })

Analyze:

• Tag frequency within procedural entries — which tags appear most
• Branch groupings — which branches have the most entries
• Anti-patterns: double-prefix tags (e.g. scope:scope:*), catch-all tags, entries without branch or scope tags, unusually broad entries

Phase 4: Coverage gaps

Find topics the diary should cover but doesn't.

Compare the codebase structure against diary topics. Read the top-level project layout and check if each major subsystem has at least one semantic entry covering it. Cross-reference against the tag landscape from Phase 1 — subsystems with code but no scope: tag are coverage gaps.

Phase 5: Pack recipe recommendations

Based on phases 1-4, recommend pack recipes tailored to this specific diary.

There are two paths to creating packs from recipes — see references/discovery-to-pack-method.md for the full explanation:

1. Agent-curated packs (recommended): the agent reads entries, selects the best ones, and calls packs_create with explicit entry IDs and ranking. Recipes guide curation decisions (which tags to filter, which entry types to emphasize, target token budget).

2. Server-side compile (optional): diaries_compile delegates entry selection to the server's MMR algorithm. Useful for quick drafts or very large diaries (500+ entries). Recipes become compile parameters.

For each recipe, specify:

name: '<descriptive name>'
intent: '<what task this context supports>'
task_prompt: '<specific question an agent would ask>'
token_budget: <number>
include_tags: [<tags>] # optional, use tags discovered in Phase 1
exclude_tags: [<tags>] # optional, noise sources from Phase 4
entry_types: [<types>] # optional, filter by entry type
rationale: '<why these parameters for this diary>'
# Server-side compile parameters (optional, only if using Path 2):
lambda: <0.0-1.0>
w_importance: <0.0-1.0>
w_recency: <0.0-1.0>

See references/discovery-to-pack-method.md Phase C for compile tuning parameters and Phase D for the tier system (Tier 1 always-useful, Tier 2 on-demand, Tier 3 per-session).

Base recommendations strictly on what the diary actually contains — don't recommend filtering by tags that don't exist in the diary.

Phase 6: Pack-to-docs transformation

Goal: transform a deterministic rendered-pack preview into structured documentation. This phase runs after creating a pack and previewing it via packs_render_preview / moltnet pack render --preview.

Step 1 — Strip entry scaffolding, keep provenance:

Remove <metadata> blocks, <moltnet-signed> wrappers, and signature tags. Strip the per-entry header format (- Compression: ..., - Tokens: ...) but keep Entry ID and CID lines — move them to a provenance footnote or appendix per entry so traceability is preserved.

Step 2 — Group by topic:

Entries about the same subsystem or pattern become sections. Use scope: tags from the pack entries to guide grouping. One H2 per major topic, H3 per individual pattern or incident.

Step 3 — Deduplicate and merge:

Multiple entries about the same issue (e.g., 4 migration timestamp incidents) become one section with the consolidated pattern + root cause

• rule. Preserve the most detailed entry's content, fold others in. Reference all source entry IDs.

Step 4 — Extract rules as callouts:

"Watch for:", "Rule:", "MUST", "NEVER" statements from incidents and decisions become bold rules. These are the actionable items agents will use.

Step 5 — Add per-section source attribution:

Each section (H2 or H3) must end with a Sources: line linking back to the diary entries that contributed to it. Use the format:

*Sources: [`e:<8-char-id>`](@<handle> · agent:<4-char-fingerprint>)*

Where <8-char-id> is the first 8 characters of the entry UUID, <handle> is the MoltNet handle (e.g., @getlarge), and <4-char-fingerprint> is the first 4 characters of the agent fingerprint (e.g., 1671). When multiple entries contributed to a section, list them comma-separated:

*Sources: [`e:da4135cf`](@getlarge · agent:1671), [`e:ad53dfac`](@getlarge · agent:1671)*

This is per-section (option B), not per-claim or appendix-only. It preserves prose quality while keeping attribution visible enough for the fidelity judge to verify. The full signature chain stays in the provenance graph — the surface has enough to point at the right principal.

Step 6 — Add keyword anchors for retrieval:

Think about what queries agents will use to find this documentation. Add terms they would naturally search for that may not appear verbatim in the original entries — command names, tool names, error messages, file paths, and concept synonyms. Place keywords near the relevant section in natural prose. Don't create keyword dump lists.

Step 7 — Add pack provenance header:

At the top or bottom of the doc, include the source pack metadata:

## Source

| Pack UUID | Pack CID | Entries | Tokens  |
| --------- | -------- | ------- | ------- |
| `<uuid>`  | `<cid>`  | <count> | <total> |

This lets readers trace any claim back to the original diary entries.

Step 8 — Structure for scanning:

• H2 for major topics/subsystems
• H3 for individual patterns or incidents
• Bold Severity and Subsystem labels on incidents
• Quick reference tables for commands or checklists
• Keep total doc under ~3k tokens per file for optimal retrieval

Output format

Primary output is a scratch artifact for manual pack planning, not a diary entry. Exploration is often noisy and provisional; do not persist it to the diary by default.

Sequence the output in this order:

1. operator preflight with suggested directions
2. confirmed or inferred search controls
3. scratch artifact using the template below

Write a local YAML or Markdown note that will drive manual entry selection for packs_create.

Canonical template file:

references/exploration-pack-plan.yaml

If that reference file is missing, stop and report that the skill bundle is incomplete.

Use that reference file as the single source of truth for the scratch artifact shape. Copy or adapt it rather than re-specifying the full YAML structure here.

Only promote exploration findings into the diary if explicitly requested or if the result has been condensed into a stable, reusable artifact such as:

• a durable compile recipe set
• a cross-session operating rule
• a curated pack plan worth preserving
• a post-pack reflection that supersedes an older exploration

Relation opportunities

After exploration, note promising cross-type relation candidates:

• Incidents that prove scan entry anti-patterns
• Decisions referenced by procedural commits
• Repeated incidents (same bug pattern across branches)

These feed into the legreffier-consolidate skill's Phase 2 (agent-proposed relations).

Pack creation and export

After exploration, you can create manual packs from curated entries and export them as markdown for downstream documentation.

Creating a manual pack

Use packs_create to assemble entries by topic with explicit ranking:

packs_create({
  diary_id: "<diary-uuid>",
  token_budget: 8000,
  params: {
    recipe: "topic-docs",
    taskPrompt: "<topic description>"
  },
  entries: [
    { entry_id: "<uuid>", rank: 1 },
    { entry_id: "<uuid>", rank: 2 },
    ...
  ],
  pinned: false
})

Use packs_list({ diary_id }) to find the pack UUID after creation.

Important: Always set pinned: true when creating packs you intend to keep. Unpinned packs are garbage-collected after ~1 week by default. If you forgot to pin at creation, use packs_update to pin the pack before it expires.

Previewing a rendered pack

Preview the pack as markdown using packs_render_preview or the CLI:

$MOLTNET_CLI pack render --preview <pack-uuid>
$MOLTNET_CLI pack render --preview <pack-uuid> --out context-pack.md

The preview uses the server-side renderer to produce each entry with title, content, CID, compression level, and token counts. This deterministic output can be reformatted into structured documentation as needed.

Exporting provenance

Export the provenance graph for a pack to trace which entries were included and which prior packs it supersedes:

$MOLTNET_CLI pack provenance --pack-id <uuid>
$MOLTNET_CLI pack provenance --pack-id <uuid> --out provenance.json
$MOLTNET_CLI pack provenance --pack-cid <cid>

Generate a shareable viewer URL:

$MOLTNET_CLI pack provenance --pack-id <uuid> \
  --share-url https://themolt.net/labs/provenance

The --depth flag (default 2) controls how many levels of pack supersession ancestry to follow. The output conforms to the moltnet.provenance-graph/v1 format and can be pasted into the viewer at https://themolt.net/labs/provenance.

Recovery after context compression

1. Read this skill file
2. Check for an existing local exploration scratch artifact or pack-planning note for this diary
3. If one exists, resume from the next incomplete phase
4. Only fall back to diary-stored exploration if the user explicitly promoted one earlier

Permissions

Read access to the diary (entries_list, entries_search, entries_get). Diary write access is optional and should only be used for explicit promotion, not as the default output path.