sage-learn

## When to Use Load this skill when the user runs `/sage-learn` or asks to learn something (the Sage learn workflow). ## Arguments Hermes does NOT interpolate an in-body argument token. The user's arguments/flags arrive as a SEPARATE instruction line appended to this skill invocation. Wherever the steps below refer to "the user's arguments", use the text of that appended instruction line. ## Independent review (delegate_task) When a step calls for an independent review, invoke `delegate_task` against the `sage-reviewer` skill. Hermes delegate_task has NO toolset-restriction parameter — read-only is prompt-enforced, and you MUST verify afterward that the reviewer made no edits (e.g. `git status` unchanged) before accepting its verdict. RULES (apply to every step — non-negotiable): - Announce: "Sage → learn workflow." before starting work - Present findings to user BEFORE storing in memory - ONTOLOGY: After storing prose knowledge, create ontology entities for structural elements (modules, services, APIs, dependencies). This builds a navigable knowledge graph. Read skills/sage-ontology/SKILL.md for encoding. Search ontology first to avoid duplicates. - Checkpoint: [A] Looks correct / [R] Some findings are wrong - Choices: present with [1] [2] [3] bracket notation - Never use code blocks for interaction (checkpoints, options, status) # Learn Workflow Deliberate knowledge capture. Use to onboard to a new codebase, deeply understand a module, or build persistent memory for a project area. ## Step 0: Mode Dispatch `/learn` builds **memory** (prose knowledge). `/learn --ontology` builds the **ontology** (a typed entity/relationship graph) instead — it folds in the former `/map` workflow. Parse `the arguments the user provided alongside this skill invocation (delivered as a separate instruction line, NOT a literal token)`: - `/learn` (default) → Steps 1–N below (memory capture). - `/learn --ontology` → read `core/workflows/learn-modes/ontology.md` and follow it; it maps modules, services, and APIs and their dependencies via the `sage-ontology` skill. ## Step 1: Determine Scope If a path is specified, that's the target — deep dive. If no path, broad scan of the whole project. Sage: What would you like to learn? [1] Broad scan — learn the project structure, stack, patterns, conventions [2] Deep dive — learn a specific module, service, or area [3] Something else — describe what you want to understand ## Step 2: Search Existing Knowledge Search sage-memory for any prior knowledge about this project or area. Don't re-learn what's already known — build on it. If prior knowledge exists, summarize: "Sage: I already know [X] about this area from previous sessions. I'll focus on what's new or missing." ## Step 3: Scan and Analyze ### Broad Scan 1. Read project structure — file tree, key directories 2. Read README, package.json / pyproject.toml / go.mod, config files 3. Identify tech stack, frameworks, build tools 4. Read entry points — main modules, routing, API surface 5. Identify architectural patterns — MVC, microservices, monolith, etc. 6. Note conventions — naming, file organization, testing approach ### Deep Dive 1. Read all files in the target area 2. Trace dependencies — what it imports, what imports it (depth 3 max) 3. Map data flow — inputs, transformations, outputs 4. Identify design patterns, error handling, edge cases 5. Assess quality — strengths, risks, technical debt ## Step 4: Review Findings Before storing knowledge, present key findings to the user. Wrong knowledge stored in memory persists into future sessions and causes confident wrong actions. **Findings quality checklist** — for each finding, verify: - **Specific?** Does it name concrete things (files, patterns, tools)? "Uses microservices" is too vague. "Uses gRPC between billing and auth services, REST for public API" is specific. - **Insight, not inventory?** Does it tell you something you can't get from `ls`? "Has a src/ directory" is inventory. "All business logic lives in src/domain/, handlers are thin wrappers" is insight. - **Actionable?** Would a future agent use this to make a better decision? If not, don't store it. If a finding fails any criterion, improve it before presenting. Sage: Here's what I found about [area]: - [Key finding 1] - [Key finding 2] - [Key finding 3-5] [A] Looks correct — store in memory [R] Some findings are wrong — let me correct them Do NOT present vague findings and rely on the user to approve them. The user may click [A] without scrutiny. The quality gate is YOUR responsibility, not the user's. If the user corrects any findings, update before storing. Store the correction as a self-learning entry (Rule 6). ## Step 5: Store Knowledge Store each finding by calling the `sage_memory_store` MCP tool directly. Each call stores one focused insight with these parameters: - **content** (string): detailed finding — what, why, implications - **title** (string): short specific title (5-15 words) - **tags** (array of strings): domain and area tags, e.g. ["billing", "auth"] - **scope** (string): "project" **MCP parameter types matter:** tags must be an actual array, not a JSON string. Pass ["billing", "auth"], not '["billing", "auth"]'. Same for all array and integer parameters across all sage-memory tools. For broad scans, aim for 10-20 calls covering: - Tech stack and framework choices - Project structure and organization - Key architectural patterns - Conventions and coding standards - Domain concepts and business logic - Notable dependencies and integrations For deep dives, aim for 5-10 calls covering: - Module purpose and role in the system - Key components and their responsibilities - Data flow and integration points - Patterns specific to this area - Risks, debt, or improvement opportunities Tag entries appropriately: - Domain tags always (e.g., `billing`, `auth`) - `ontology` tag for entity relationships and dependencies - `learning` tag for gotchas or non-obvious behavior discovered If `sage_memory_store` is not available, fall back to `.sage-memory/` files. For each finding, create a file using the format defined in the sage-memory skill's Storage Priority section. Filename = kebab-case title. ### Ontology Bootstrapping After storing prose knowledge, create ontology entities for the structural elements you discovered. This builds a knowledge graph that keeps the codebase's architecture navigable across sessions. **For broad scans, create entities for:** - Each major module or service → `Project` entity (name, status: active) - Key inter-module dependencies → `depends_on` relations - Entry points (APIs, CLI commands, main routes) → `Document` entities **For deep dives, create entities for:** - The module itself → `Project` entity if not already in graph - Key internal components → `Task` entities (as sub-units of work) - Dependencies this module has on other modules → `depends_on` relations - Services it calls or is called by → `depends_on` relations **Keep it lightweight:** - Only create entities for things a future agent needs to navigate (modules, services, APIs, dependencies) — not every file or function - Search ontology first (`sage_memory_search: tags=["ontology"]`) to avoid duplicating existing entities - 5-15 ontology entries for broad scans, 3-8 for deep dives - Use the encoding format from `skills/sage-ontology/SKILL.md` ## Step 6: Generate Knowledge Report Save a human-readable report to `.sage/docs/memory-{name}.md`. Follow the sage-memory skill's `references/knowledge-report.md` guide: - Adapt structure to content (don't force a rigid template) - Include mermaid diagrams when they clarify architecture or data flow - Focus on insights, not inventory - Note how many memory entries were stored ## Step 7: Report Summary Sage: Learning complete — [area name] Knowledge stored: • [X] memories in sage-memory • Report: .sage/docs/memory-{name}.md Key findings: • [Top 3-4 insights, one line each] [C] Continue — learn another area Next steps: /build — spec → plan → implement → verify /research — interview → JTBD → opportunity map /reflect — review what you learned, extract patterns Type a command, or describe what you want to do next. ## Rules - Search before storing — don't duplicate existing knowledge. - Store insights, not facts readable from files. - One insight per memory entry — focused entries retrieve precisely. - Adapt depth to scope — broad scans stay high-level, deep dives trace dependencies and assess quality. - The knowledge report is for humans. Memory entries are for the agent. Both should exist for significant learning.