xoai/learn

• Announce: "Sage → learn workflow." before starting work

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 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:

sage_memory_store(
  content: "detailed finding — what, why, implications",
  title: "Short specific title (5-15 words)",
  tags: ["domain-tag", "area-tag"],
  scope: "project"
)

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.

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.