# Mine Document > Use when the user says: "document how X works", "write up how this works", "durable explanation", "explain this for the docs", "document this subsystem". Writes a durable, architectural-altitude explanation that survives code churn. - Skill: `nodejsmith/mine-document` (Agent Skill) - Install (CLI): `npx skillmds@latest add nodejsmith/mine-document` - Raw SKILL.md: https://api.skillmd.com/api/skills/nodejsmith/mine-document/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: NodeJSmith (https://skillmd.com/u/nodejsmith) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/nodejsmith/mine-document --- # Document Writes a durable explanation of a subsystem, flow, or mechanism — one that stays accurate across routine code changes because it describes **shape and responsibility**, not lines and locals. ## How This Differs From Other Skills | Skill | What it produces | |-------|-----------------| | **`/mine-document`** | **Durable write-up — describes components, flows, and decisions at architectural altitude** | | `/mine-how` | Conversational walkthrough — builds a mental model with file:line provenance, ephemeral | | `architect` agent | Living architecture overview — Mermaid diagrams, narrative docs, TBD-tracking, whole-codebase scope | | `/mine-research` | Investigation brief — evaluates feasibility of a proposed change | The key distinction from `/mine-how`: that skill pins every claim to a line number, which makes it precise but fragile. This skill anchors to **named components and file-level references**, which survive refactors, renames within a file, and line count changes. The tradeoff is less precision — a reader may need to open a file and search, rather than jumping to an exact line. ## Arguments $ARGUMENTS — what to document. Can be: - A subsystem: `/mine-document "the challenge pipeline"` - A runtime flow: `/mine-document "webhook ingestion"` - A mechanism: `/mine-document "rate limiting"` - A file/module: `/mine-document src/services/auth.py` - Empty: ask the user what they want documented ## Phase 1: Scope Run `get-skill-tmpdir mine-document` to establish `` for all intermediate files. If $ARGUMENTS is empty: ``` AskUserQuestion: question: "What would you like me to document?" header: "Subject" multiSelect: false options: - label: "I'll type the subject" description: "Name a subsystem, flow, or mechanism in this codebase" - label: "Suggest a subject" description: "Scan the codebase and suggest subsystems worth documenting" ``` If "Suggest a subject": scan the codebase for documentation candidates — look at directory structure, recently modified files (`git log -n 20 --diff-filter=M --name-only --format=`), and large files. Identify 2-3 subsystems that are complex enough to benefit from a durable explanation. Present them via `AskUserQuestion` with a brief rationale for each. Then ask where the output should go: ``` AskUserQuestion: question: "Where should I write the document?" header: "Output" multiSelect: false options: - label: "docs/ directory" description: "Write to docs/document-.md" - label: "design/ directory" description: "Write to design/document-.md" ``` Derive `` from the subject (kebab-case, max ~40 chars). Determine the full output path from the chosen directory + slug. **Existing file check:** If the target path already exists, read its content and hold it as `` — it will be passed to investigation/synthesis agents in Phase 2 so manually-added material can be preserved. Confirm with the user before proceeding: ``` AskUserQuestion: question: "A document already exists at . Re-investigate and overwrite?" header: "Overwrite" multiSelect: false options: - label: "Overwrite (Recommended)" description: "Re-investigate and replace — prior content will be passed as context to preserve hand-edits where supported" - label: "Cancel" description: "Keep the existing file unchanged" ``` If "Cancel": stop. Tell the user the existing file is unchanged. Assess complexity: - **Simple** — the answer lives in 3 or fewer files. - **Complex** — 4+ files or cross-module flows. Default to complex when uncertain. ## Phase 2: Investigate ### Check prior conversations Run: ```bash ccrecall --json search-messages -q "" -n 5 ``` If it returns relevant matches, condense them into a short digest (what was discussed, when) to pass along as `` — useful for the "Key decisions and invariants" section, since rationale is often discussed in conversation and never written into a commit or doc. If nothing relevant comes back, skip this — don't pad the prompt with a null result. ### Simple path Dispatch one agent: ``` Agent(subagent_type: "standard-worker") ``` Prompt: ``` Write a durable subsystem explanation based on actual code. Subject: [If exists] Prior version of this document (preserve manually-added material that the investigation still supports): [If exists] A past conversation touched on this — verify it against current code before relying on it, don't trust it blindly: Instructions: 1. Find the relevant files using Grep and Glob 2. Read each file that contributes to the answer 3. Trace the runtime flow — what calls what, what data flows where 4. Write the explanation to /explanation.md Writing rules: - Conversational tone — explain like a knowledgeable teammate, not a reference manual - Anchor to NAMED COMPONENTS (files, classes, functions that are stable API surfaces) - Describe RESPONSIBILITIES and FLOW — the decisions and shape, not transient implementation details - Explain WHY the system is shaped this way, not just the structure - Name INVARIANTS — things the system relies on that aren't obvious from one file - Describe DATA SHAPES at boundaries — what goes in, what comes out, in what form (shape-level, not exhaustive field enumeration) - If something is unclear or seems wrong in the code, say so - Keep it at senior-engineer depth - Never include: line numbers, internal variable names, method names that aren't stable API surfaces, exhaustive parameter lists Structure the document as: 1. One-paragraph overview (what this subsystem does and why it exists) 2. Components and their responsibilities (which files own what) 3. The flow (walk through runtime behavior as a narrative) 4. Key decisions and invariants (why it's shaped this way, what must stay true) 5. Boundaries (what this subsystem expects from its callers and dependencies) ``` ### Complex path Decompose the question into 2-4 investigation angles. Each angle should cover a distinct aspect. Examples: - "Entry point and dispatch" / "Error handling path" / "State management" - "Data flow in" / "Processing" / "Data flow out" - "Configuration and setup" / "Runtime behavior" / "Shutdown and cleanup" Dispatch 2-4 parallel explorer agents: ``` Agent(subagent_type: "light-worker") # for each angle ``` Each explorer prompt: ``` Investigate one aspect of a subsystem for a durable explanation being assembled. Subject: Your angle: Instructions: 1. Find files relevant to your angle using Grep and Glob 2. Read each file and trace the flow specific to your angle 3. Write your findings to /explorer-N.md Include: - File paths (no line numbers) for every claim - The sequence of calls or data flow you traced - Component responsibilities within your angle - Anything surprising, unclear, or potentially wrong Stay focused on your angle — other explorers are covering other aspects. ``` After all explorers complete, dispatch a synthesis agent: ``` Agent(subagent_type: "standard-worker") ``` Synthesis prompt: ``` Synthesize explorer findings into a durable subsystem explanation. Subject: [If exists] Prior version of this document (preserve manually-added material that the investigation still supports): [If exists] A past conversation touched on this — verify it against current code before relying on it, don't trust it blindly: Explorer findings (read each file): Instructions: 1. Read all explorer findings 2. If explorers conflict on the same code path, read the code directly to resolve 3. Write the explanation to /explanation.md Writing rules: - Conversational tone — explain like a knowledgeable teammate, not a reference manual - Anchor to NAMED COMPONENTS (files, classes, functions that are stable API surfaces) - Describe RESPONSIBILITIES and FLOW — the decisions and shape, not transient implementation details - Explain WHY the system is shaped this way, not just the structure - Name INVARIANTS — things the system relies on that aren't obvious from one file - Describe DATA SHAPES at boundaries — what goes in, what comes out, in what form (shape-level, not exhaustive field enumeration) - Where explorers found surprising or unclear code, call it out - Keep it at senior-engineer depth - Never include: line numbers, internal variable names, method names that aren't stable API surfaces, exhaustive parameter lists Structure the document as: 1. One-paragraph overview (what this subsystem does and why it exists) 2. Components and their responsibilities (which files own what) 3. The flow (walk through runtime behavior as a narrative) 4. Key decisions and invariants (why it's shaped this way, what must stay true) 5. Boundaries (what this subsystem expects from its callers and dependencies) ``` ## Phase 3: Coherence Review This replaces `/mine-how`'s line-level accuracy review with a structural coherence check. The question isn't "does line 45 say what I claimed?" but "does the code's shape match what I described?" Dispatch a review agent: ``` Agent(subagent_type: "standard-worker") ``` Review prompt: ``` Review this durable explanation for structural accuracy. Subject: Explanation: /explanation.md (read this file) Instructions: 1. Read the explanation 2. For every file reference, open that file and verify: - Does the component exist and have the described responsibility? - Does the described flow match the actual call chain? - Are the named invariants real? - Do the data shapes at boundaries match? 3. Check for: - Components described that don't exist or do something different - Flow descriptions that skip steps or get the order wrong - Claims about behavior the code doesn't support - Missing important components or flows the explanation should cover - Implementation details that crept in (line numbers, local variable names, exhaustive parameter lists, unstable internal method names) - Documentation-mode drift: numbered instructional steps, exhaustive field-by-field catalogs, or anything phrased as a procedure for the reader to perform — flag and rewrite as descriptive narrative. Scrutinize the Boundaries section especially, since boundary/contract content is the most prone to drifting into reference-mode enumeration. 4. Write your review to /review.md Output format: - If accurate: write "ACCURATE" on the first line, then optionally note any additions that would strengthen the explanation - If corrections needed: write "CORRECTIONS" on the first line, then write a corrected version of the full explanation. Annotate each correction with [CORRECTED: reason]. ``` ## Phase 4: Write After the review completes, read `/review.md`: - If "ACCURATE": use `/explanation.md` as the source - If "CORRECTIONS": use the corrected version from the review file, stripping `[CORRECTED: ...]` annotations Add a provenance footer to the document. Run `git rev-parse --short HEAD` to get the current commit SHA. ```markdown --- *Generated by `/mine-document` against commit ``. If the codebase has changed significantly since this commit, re-run to refresh.* ``` Write the file to the chosen location. Present a brief summary to the user (what it covers, where it landed), not the full document — they can read the file.