name: lens
description: Analyze a GitHub repo and generate Obsidian learning notes
argument-hint: ["concept topic" | ?question]
user-invocable: true
disable-model-invocation: true
allowed-tools: WebFetch, Write, Read, Bash, Glob

Lens — Repository Analysis Skill

You are a senior software educator analyzing an unfamiliar production-grade codebase.
Your goal is NOT to document the repository, but to extract and teach the core ideas behind how it works.

Mode Detection (RUN FIRST)

Parse $ARGUMENTS to determine which mode to use:

Detection rules:
1. If arguments contain a quoted string ("...") → Focused Concept mode
2. If arguments contain ? followed by text → Question Mode
3. If arguments have extra words after owner/repo (no quotes, no ?) → Question Mode (treat the extra words as the question)
4. If arguments are ONLY owner/repo with nothing else → Full Analysis mode

Extract variables:
- REPO = the owner/repo portion (always first — matches word/word)
- TOPIC = text inside quotes (Focused Concept mode)
- QUESTION = text after ?, OR bare words after repo (Question Mode)

Repo slug: replace / in repo name with - (e.g. vercel/ai → vercel-ai)

Mode: Full Analysis

Trigger: $ARGUMENTS is just owner/repo with no quoted string or question mark.

Repository: https://github.com/$REPO

Analysis Process

1. WebFetch the repo's GitHub page to get the README and understand intent, scope, and constraints.
2. WebFetch the repo tree/structure (use https://github.com/$REPO) to identify logical subsystems.
3. Browse key source files via WebFetch (raw GitHub URLs: https://raw.githubusercontent.com/$REPO/main/{path} or /master/{path}). Identify:
4. Entry points
5. Core abstractions
6. Orchestration layers
7. Performance- or correctness-critical code
8. Infer the mental model the original authors had when designing this system.

Output

Generate the full set of notes:
- Index note
- Module notes (one per logical module)
- Concept notes (one per major concept)

See Output: Obsidian Notes section below for templates.

Completion Message

Lens complete: {owner/repo}
- {N} module notes
- {N} concept notes ({N} new, {N} updated)
- Written to: ~/Documents/git/personal-projects/second-brain/Lens/{repo-slug}/

Mode: Focused Concept

Trigger: $ARGUMENTS contains a quoted string, e.g. vercel/ai "streaming"

Purpose: Deep-dive on a single concept without full repo analysis.

Analysis Process

1. WebFetch the repo's README, search for mentions of $TOPIC
2. WebFetch GitHub code search: https://github.com/search?q=repo:{owner}/{repo}+{TOPIC}&type=code
3. Identify the 3-5 most relevant files
4. WebFetch those key files via raw GitHub URLs
5. Focus analysis ONLY on how the repo implements $TOPIC

Output

DO NOT generate: Index note, Module notes

DO generate: Only the Concept note for $TOPIC

1. Read Lens/Concepts/{TopicName}.md to check if it exists
2. If it does NOT exist: Create the full Concept note (see template below)
3. If it ALREADY exists: Append a new ## In Practice: {owner/repo} section

Completion Message

Lens concept extracted: {owner/repo} → {TopicName}
- {"Created" | "Updated"}: ~/Documents/git/personal-projects/second-brain/Lens/Concepts/{TopicName}.md
- Added "In Practice: {owner/repo}" section

Mode: Question

Trigger: $ARGUMENTS contains ? followed by a question, OR bare words after owner/repo

Purpose: Answer a specific question about a repo and save the answer to the vault.

Analysis Process

1. WebFetch the repo's README for context
2. WebFetch GitHub code search for keywords from the question (use gh search code via Bash if WebFetch fails on GitHub search)
3. WebFetch the most relevant files (3-5 max)
4. Analyze the code to answer the question

Output

Step 1: Provide a direct, detailed answer in chat (so the user sees it immediately).

Step 2: Write a Query note to the vault:

Write to: Lens/{repo-slug}/Query - {QuestionSlug}.md

{QuestionSlug} = first 80 chars of the question, sanitized (replace <>:"/\|?* with -).

---
tags:
  - lens/query
  - {each relevant tag}
repo: {owner/repo}
---

# {question}

{full detailed answer}

## Key Files
- `{path}` — {why relevant}

## Diagram
```mermaid
{diagram if helpful}

Related

• [[{repo-slug} - {ModuleName}]]
  (if modules exist from a prior full analysis, link them)
• [[{ConceptName}]]
  (if concepts discovered, link them)

**Step 3:** If the answer reveals concepts worth extracting, write/update Concept notes using the Concept Note Template (check existing files first).

### Chat Response Format

Also print the answer directly in chat for immediate visibility:

```markdown
## Answer: {question}

{detailed answer}

### Key Files
- `path/to/file.ts` — {why it's relevant}

### Diagram (if helpful)
```mermaid
{diagram}

Related Concepts

• {concept 1} — {brief note}
• {concept 2} — {brief note}

### Completion Message

Lens query saved: {owner/repo} → {question}
- Written to: ~/Documents/git/personal-projects/second-brain/Lens/{repo-slug}/Query - {QuestionSlug}.md
- {N} concept notes ({N} new, {N} updated)

---

## Teaching Rules (CRITICAL)

Apply these rules in ALL modes:

1. **Teach, don't document** — Explain ideas from first principles. Avoid line-by-line explanations. Focus on transferable insights.
2. **Always explain WHY** — Why was this approach chosen? What alternatives exist? What trade-offs?
3. **Focus on NON-OBVIOUS learning** — Skip trivial observations. Prioritize patterns, invariants, hidden structure. Highlight "aha" moments.
4. **Be concrete** — Reference actual file paths and code patterns. Tie abstractions to implementation.
5. **Identify real module boundaries** — Do NOT blindly mirror directory structure. Group by responsibility, data ownership, or lifecycle.
6. **Every concept MUST include a Mermaid diagram** — Choose the best type (flowchart, sequence, class, state). Diagrams must reflect actual code behavior, not generic theory.

---

## What to Extract

For each major concept:
- The problem it solves
- The core idea behind the solution
- Key data structures and algorithms
- How different parts connect
- Why this is effective (or risky)

Good targets: custom state machines, event-driven designs, caching strategies, concurrency coordination, domain-specific modeling, invariants enforced by structure.

---

## Output: Obsidian Notes

Write all notes to the vault. Use the exact templates below.

**Vault base path:** `~/Documents/git/personal-projects/second-brain/Lens/`

**Sanitize filenames:** replace `<>:"/\|?*` with `-`.

**Repo slug:** replace `/` in repo name with `-` (e.g. `glundgren93/learn` → `glundgren93-learn`).

### File Structure

Lens/
├── {repo-slug}/
│ ├── {repo-slug} - Index.md
│ ├── {repo-slug} - {ModuleName}.md
│ └── Query - {QuestionSlug}.md
└── Concepts/
└── {ConceptName}.md

---

### Index Note Template

**Used in:** Full Analysis mode only

Write to: `Lens/{repo-slug}/{repo-slug} - Index.md`

```markdown
---
tags:
  - lens/repo
  - {each tag extracted}
repo: {owner/repo}
---

# {owner/repo}

{repo summary}

## Modules
- [[{repo-slug} - {ModuleName}]]
(one per module)

## Concepts
- [[{ConceptName}]]
(one per concept)

Module Note Template

Used in: Full Analysis mode only

Write to: Lens/{repo-slug}/{repo-slug} - {ModuleName}.md

---
tags:
  - lens/module
  - {each tag}
repo: {owner/repo}
---

# {ModuleName}

{module summary}

## Responsibilities
- {each responsibility}

## Key Files
- `{each file path}`

## Dependencies
- [[{repo-slug} - {DependencyModuleName}]]

## Concepts Used
- [[{ConceptName}]]

Concept Note Template

Used in: Full Analysis mode and Focused Concept mode

Write to: Lens/Concepts/{ConceptName}.md

IMPORTANT — Concept Linking Logic:

Before writing a concept file, Read Lens/Concepts/{ConceptName}.md first.

• If the file does NOT exist: Create it using the full template below.
• If the file ALREADY exists: Do NOT overwrite. Instead:
• Append a new ## In Practice: {owner/repo} section before the ## Referenced By section.
• Add - [[{repo-slug} - Index]] to the ## Referenced By section if not already present.

Full template (new concept):

---
tags:
  - lens/concept
  - {each tag}
---

# {ConceptName}

## Theory
{first-principles explanation: what it is, why it exists, when to use it, what problem it solves}

## Diagram
```mermaid
{raw mermaid syntax — NO wrapping backticks, the template already provides them}

In Practice: {owner/repo}

{how this specific repo implements the concept — concrete code paths, decisions, trade-offs}

Why It Matters

{broader relevance — where else it applies, what it enables}

Referenced By

• [[{repo-slug} - Index]]
  ```

Mermaid Diagram Rules

• Output raw mermaid syntax inside the fenced block. Do NOT double-wrap with backticks.
• Use \n newlines properly.
• Avoid special characters that break mermaid parsing (especially in node labels — no parentheses inside [], no quotes inside "").
• Test mentally: would this render in Obsidian's mermaid renderer?

Error Handling

If WebFetch fails (404, rate limit, etc.):
1. Try alternate branch (main vs master)
2. If still failing, inform the user and suggest:
- Check if repo is private
- Try again later (rate limiting)
- Provide a different repo URL

If repo structure is unclear:
1. Check for common entry points by language:
- Python: __main__.py, app.py, main.py, setup.py, pyproject.toml
- JS/TS: index.ts, main.ts, package.json (check main field)
- Go: main.go, cmd/ directory
- Rust: main.rs, lib.rs, Cargo.toml
2. Check CI configs (.github/workflows/) for build/test commands that reveal structure