Learn

Preamble (run first)

_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//'  || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"learn","phase":"idea","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' 
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"learn","phase":"idea","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi

If TEL_PROMPTED is no: Before starting the skill workflow, ask the user about telemetry. Use AskUserQuestion:

Help superstack get better! We track which skills get used and how long they take — no code, no file paths, no PII. Change anytime in ~/.superstack/config.json.

Options:

• A) Sure, help superstack improve (anonymous)
• B) No thanks

If A: run this bash:

echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted

If B: run this bash:

echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted

This only happens once. If TEL_PROMPTED is yes, skip this entirely and proceed to the skill workflow.

Wrong skill? See SKILL_ROUTER.md for all available skills.

Adapted from gstack learn skill.

Project Learnings

You manage the project's knowledge base. Learnings are stored in a single human-readable markdown file at .superstack/learnings.md, grouped by type: Patterns, Pitfalls, Preferences, Architecture, and Tools. Each entry has a key, insight, confidence score, source skill, relevant files, and date.

This skill is read/write for the learnings file ONLY. You never modify project code.

Commands

Learnings File Format

File: .superstack/learnings.md

# Project Learnings

> Managed by `/learn`. Append-only — latest entry wins on conflicts.

## Patterns

### pda-seed-convention
- **Insight:** Use [program_id, user_pubkey, "vault"] as PDA seeds
- **Confidence:** 8/10
- **Source:** build-with-claude
- **Files:** programs/src/lib.rs
- **Date:** 2026-03-28

## Pitfalls

### cpi-signer-missing
- **Insight:** CPI calls require PDA signer seeds, not just the address
- **Confidence:** 9/10
- **Source:** debug-program
- **Files:** programs/src/instructions/settle.rs
- **Date:** 2026-03-28

## Preferences

(entries here)

## Architecture

(entries here)

## Tools

(entries here)

Each entry follows this structure:

### kebab-case-key
- **Insight:** One clear sentence describing the learning
- **Confidence:** N/10
- **Source:** skill-name-that-generated-this
- **Files:** relevant/file/path.rs, another/file.ts (optional)
- **Date:** YYYY-MM-DD

Command Implementations

Show Recent (/learn)

1. Read .superstack/learnings.md
2. If the file does not exist, respond: "No learnings yet. As you use skills, superstack captures patterns and insights automatically. Use /learn add to manually record something."
3. Parse all entries across all type sections
4. Display the 20 most recent entries (sorted by Date descending)
5. Show total count at the bottom: "Showing 20 of N total learnings."

Search (/learn search <query>)

1. Read .superstack/learnings.md
2. Search across all entry fields (key, insight, source, files) for the query string (case-insensitive)
3. Display all matching entries, grouped by type
4. If no matches: "No learnings match '{query}'. Try a broader search or check /learn stats for what's recorded."

Prune (/learn prune)

1. Read all entries from .superstack/learnings.md
2. For each entry that has a Files field:
   • Use Glob to check if the referenced files still exist
   • If any file is missing, flag the entry as stale
3. Check for contradictions:
   • Entries with the same key but different insights
   • Entries where one says "do X" and another says "don't do X" on related topics
4. For each flagged entry, present via AskUserQuestion:
   • A) Remove — delete the entry
   • B) Keep — mark as still valid (update date to today)
   • C) Update — provide a new insight (ask for the updated text)
5. Apply changes and save the file

Export (/learn export)

1. Read all entries from .superstack/learnings.md
2. Format as a clean markdown section:

## Learnings

Key patterns, pitfalls, and preferences discovered during development.

### Patterns
- **pda-seed-convention:** Use [program_id, user_pubkey, "vault"] as PDA seeds (8/10)
- **another-pattern:** Description here (7/10)

### Pitfalls
- **cpi-signer-missing:** CPI calls require PDA signer seeds, not just the address (9/10)

### Preferences
...

### Architecture
...

### Tools
...

3. Use AskUserQuestion to ask: "Where should I put the exported learnings?"
   • A) Append to CLAUDE.md — add the section at the end of the project's CLAUDE.md
   • B) Save to .superstack/learnings-export.md — standalone file
   • C) Print only — display without saving

Stats (/learn stats)

1. Read all entries from .superstack/learnings.md
2. Compute and display as a table: