learn

Learn Skill

When to Use

• User types /learn in chat
• User asks to "save this as a learning", "remember this", or "add this to learnings"
• User corrects you and you want to persist that correction for future sessions

How It Works

1. Review the full conversation thread
2. Identify corrections, preferences, data mappings, workflow insights, and gotchas
3. Save each learning via POST /api/learn
4. Confirm what was saved

API Endpoint

POST /api/learn

Appends a structured entry to docs/learnings.md.

Structured entry (preferred for individual learnings):

{
  "category": "User Preferences",
  "insight": "Always filter out internal team emails when showing customer-specific activity",
  "source": "User correction during customer dashboard session"
}

Raw markdown (for complex multi-line entries):

{
  "rawMarkdown": "### Customer Data\n\n**Example Corp** org ID: `example-org-id`. Primary contact: jane@example.com."
}

GET /api/learn

Returns the current contents of docs/learnings.md as { content: string }.

Valid Categories

Use one of the existing section headers from docs/learnings.md:

• Agent Behavior Rules
• Customer Data
• User Preferences
• UI Patterns
• Dashboard Data Fetching Pattern
• Reusable Scripts
• Cross-Referencing Customers Across Services

Use Other if none fit — the learning will be appended at the end of the file.

What to Extract

When reviewing a thread, focus on:

Signal	Example
User corrections	"No, that metric should use signup not sign_up"
Data source mappings	"Example Corp org IDs are X, Y, Z"
Query patterns	"Always join on dim_hs_contacts for customer lookups"
Preferences	"I prefer stacked bar charts for per-user breakdowns"
Gotchas	"The data column is JSON — use JSON_VALUE() to extract"
Workflow insights	"Check Grafana before looking at code for incidents"

Skip obvious or trivial observations. Each learning should be actionable — what to do, what not to do, and why.

Example Flow

User types /learn. Agent responds:

1. Scan the thread for corrections and insights
2. For each learning found, call POST /api/learn:

   POST /api/learn
   { "category": "Customer Data", "insight": "Example Corp org ID is `example-org-id`", "source": "Thread with Steve" }
   

3. Summarize what was saved:

   Saved 3 learnings to docs/learnings.md:

   • Customer Data: Example Corp org ID is example-org-id
   • User Preferences: Use dark theme for all exported charts
   • Agent Behavior Rules: Always check Sentry before investigating code for error spikes

Gotchas

• Always read docs/learnings.md first to avoid duplicating existing entries
• Keep insights concise — one actionable point per entry
• Use the structured format (category + insight + source) for most entries; raw markdown only for complex multi-line content
• The source field is optional but helpful for traceability