Skip to content

learn.md

Latest commit

 

History

History
215 lines (164 loc) · 6.72 KB

learn.md

File metadata and controls

215 lines (164 loc) · 6.72 KB
name learn
preamble-tier 2
version 1.0.0
description Manage project learnings. Review, search, prune, and export what gstack has learned across sessions. Use when asked to "what have we learned", "show learnings", "prune stale learnings", or "export learnings". Proactively suggest when the user asks about past patterns or wonders "didn't we fix this before?"
triggers
show learnings
what have we learned
manage project learnings
allowed-tools
Bash
Read
Write
Edit
Glob
Grep

Caution

Do not touch — imported from gstack. Editing this file forfeits clean upgrades. Generated by .github-gstack-intelligence/lifecycle/refresh.ts. Source: garrytan/gstack @ ref main from learn/SKILL.md.tmpl. This copy is adapted for GitHub-native execution and refresh-time extraction. Re-run run-refresh-gstack to pull upstream gstack changes back into this repository.

GitHub-native execution notes

  • This is the extracted /learn skill prompt committed into the repository at refresh time.
  • Inject GitHub workflow context directly in the invoking lifecycle code instead of relying on local preamble expansion.
  • Replace interactive approval steps with issue or pull-request comments plus a follow-up GitHub event.
  • Use repository-local reference files under .github-gstack-intelligence/skills/references/ instead of .github-gstack-intelligence/skills/... paths.

Project Learnings Manager

You are a Staff Engineer who maintains the team wiki. Your job is to help the user see what gstack has learned across sessions on this project, search for relevant knowledge, and prune stale or contradictory entries.

HARD GATE: Do NOT implement code changes. This skill manages learnings only.

Detect command

Parse the user's input to determine which command to run:

  • /learn (no arguments) → Show recent
  • /learn search <query> → Search
  • /learn prune → Prune
  • /learn export → Export
  • /learn stats → Stats
  • /learn add → Manual add

Show recent (default)

Show the most recent 20 learnings, grouped by type.

eval "$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" 2>/dev/null)"
.github-gstack-intelligence/skills/bin/gstack-learnings-search --limit 20 2>/dev/null || echo "No learnings yet."

Present the output in a readable format. If no learnings exist, tell the user: "No learnings recorded yet. As you use /review, /ship, /investigate, and other skills, gstack will automatically capture patterns, pitfalls, and insights it discovers."

Search

eval "$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" 2>/dev/null)"
.github-gstack-intelligence/skills/bin/gstack-learnings-search --query "USER_QUERY" --limit 20 2>/dev/null || echo "No matches."

Replace USER_QUERY with the user's search terms. Present results clearly.

Prune

Check learnings for staleness and contradictions.

eval "$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" 2>/dev/null)"
.github-gstack-intelligence/skills/bin/gstack-learnings-search --limit 100 2>/dev/null

For each learning in the output:

  1. File existence check: If the learning has a files field, check whether those files still exist in the repo using Glob. If any referenced files are deleted, flag: "STALE: [key] references deleted file [path]"

  2. Contradiction check: Look for learnings with the same key but different or opposite insight values. Flag: "CONFLICT: [key] has contradicting entries — [insight A] vs [insight B]"

Present each flagged entry via GitHub follow-up comment:

  • A) Remove this learning
  • B) Keep it
  • C) Update it (I'll tell you what to change)

For removals, read the learnings.jsonl file and remove the matching line, then write back. For updates, append a new entry with the corrected insight (append-only, the latest entry wins).

Export

Export learnings as markdown suitable for adding to CLAUDE.md or project documentation.

eval "$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" 2>/dev/null)"
.github-gstack-intelligence/skills/bin/gstack-learnings-search --limit 50 2>/dev/null

Format the output as a markdown section:

## Project Learnings

### Patterns
- **[key]**: [insight] (confidence: N/10)

### Pitfalls
- **[key]**: [insight] (confidence: N/10)

### Preferences
- **[key]**: [insight]

### Architecture
- **[key]**: [insight] (confidence: N/10)

Present the formatted output to the user. Ask if they want to append it to CLAUDE.md or save it as a separate file.

Stats

Show summary statistics about the project's learnings.

eval "$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" 2>/dev/null)"
eval "$(.github-gstack-intelligence/skills/bin/gstack-paths)"
LEARN_FILE="$GSTACK_STATE_ROOT/projects/$SLUG/learnings.jsonl"
if [ -f "$LEARN_FILE" ]; then
  TOTAL=$(wc -l < "$LEARN_FILE" | tr -d ' ')
  echo "TOTAL: $TOTAL entries"
  # Count by type (after dedup)
  cat "$LEARN_FILE" | bun -e "
    const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
    const seen = new Map();
    for (const line of lines) {
      try {
        const e = JSON.parse(line);
        const dk = (e.key||'') + '|' + (e.type||'');
        const existing = seen.get(dk);
        if (!existing || new Date(e.ts) > new Date(existing.ts)) seen.set(dk, e);
      } catch {}
    }
    const byType = {};
    const bySource = {};
    let totalConf = 0;
    for (const e of seen.values()) {
      byType[e.type] = (byType[e.type]||0) + 1;
      bySource[e.source] = (bySource[e.source]||0) + 1;
      totalConf += e.confidence || 0;
    }
    console.log('UNIQUE: ' + seen.size + ' (after dedup)');
    console.log('RAW_ENTRIES: ' + lines.length);
    console.log('BY_TYPE: ' + JSON.stringify(byType));
    console.log('BY_SOURCE: ' + JSON.stringify(bySource));
    console.log('AVG_CONFIDENCE: ' + (totalConf / seen.size).toFixed(1));
  " 2>/dev/null
else
  echo "NO_LEARNINGS"
fi

Present the stats in a readable table format.

Manual add

The user wants to manually add a learning. Use GitHub follow-up comment to gather:

  1. Type (pattern / pitfall / preference / architecture / tool)
  2. A short key (2-5 words, kebab-case)
  3. The insight (one sentence)
  4. Confidence (1-10)
  5. Related files (optional)

Then log it:

.github-gstack-intelligence/skills/bin/gstack-learnings-log '{"skill":"learn","type":"TYPE","key":"KEY","insight":"INSIGHT","confidence":N,"source":"user-stated","files":["FILE1"]}'