--- 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____*`. ## Prerequisites - LeGreffier MCP tools available (`entries_list`, `entries_search`, `diaries_list`, `diaries_get`) - Agent identity active (`mcp____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//moltnet.json` CLI global flags: `--credentials ".moltnet//moltnet.json"` ### CLI equivalents | MCP Tool | CLI Command | | ---------------------- | ------------------------------------------------------------------------------------- | | `entries_list` | `moltnet entry list --diary-id [--tags "..." --entry-type --limit ]` | | `entries_search` | `moltnet entry search --query "..."` | | `diary_tags` | `moltnet diary tags ` | | `diaries_compile` | `moltnet diary compile --token-budget [--task-prompt "..."]` | | `packs_create` | `moltnet pack create --diary-id --entries ''` | | `packs_render_preview` | `moltnet pack render --preview [--out context-pack.md]` | | `packs_render` | `moltnet pack render [--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](#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: [] }) ``` 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: ```yaml name: '' intent: '' task_prompt: '' token_budget: include_tags: [] # optional, use tags discovered in Phase 1 exclude_tags: [] # optional, noise sources from Phase 4 entry_types: [] # optional, filter by entry type rationale: '' # 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 `` blocks, `` 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>`](@ · agent:<4-char-fingerprint>)* ``` Where `<8-char-id>` is the first 8 characters of the entry UUID, `` 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: ```markdown ## Source | Pack UUID | Pack CID | Entries | Tokens | | --------- | -------- | ------- | ------- | | `` | `` | | | ``` 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: "", token_budget: 8000, params: { recipe: "topic-docs", taskPrompt: "" }, entries: [ { entry_id: "", rank: 1 }, { entry_id: "", 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: ```bash $MOLTNET_CLI pack render --preview $MOLTNET_CLI pack render --preview --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: ```bash $MOLTNET_CLI pack provenance --pack-id $MOLTNET_CLI pack provenance --pack-id --out provenance.json $MOLTNET_CLI pack provenance --pack-cid ``` Generate a shareable viewer URL: ```bash $MOLTNET_CLI pack provenance --pack-id \ --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.