learn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/learn - Deep Dive Learning Pattern

/learn - 深度探索学习模式

Explore a codebase with 3 parallel Haiku agents → create organized documentation.

借助3个并行的Haiku Agent探索代码库 → 生成结构化文档。

Usage

使用方法

/learn [url]             # Auto: clone via ghq, symlink origin/, then explore
/learn [slug]            # Use slug from ψ/memory/slugs.yaml
/learn [repo-path]       # Path to repo
/learn [repo-name]       # Finds in ψ/learn/owner/repo
/learn --init            # Restore all origins after git clone (like submodule init)

/learn [url]             # Auto: clone via ghq, symlink origin/, then explore
/learn [slug]            # Use slug from ψ/memory/slugs.yaml
/learn [repo-path]       # Path to repo
/learn [repo-name]       # Finds in ψ/learn/owner/repo
/learn --init            # Restore all origins after git clone (like submodule init)

Depth Modes

深度模式

Flag	Agents	Files	Use Case
`--fast`	1	1 overview	Quick scan, "what is this?"
(default)	3	3 docs	Normal exploration
`--deep`	5	5 docs	Master complex codebases

/learn --fast [target]   # Quick overview (1 agent, ~2 min)
/learn [target]          # Standard (3 agents, ~5 min)
/learn --deep [target]   # Deep dive (5 agents, ~10 min)

标记	Agent数量	生成文档数	使用场景
`--fast`	1	1份概览文档	快速扫描，适用于“这是什么项目？”的需求
(默认)	3	3份文档	常规代码库探索
`--deep`	5	5份文档	深入学习复杂代码库

/learn --fast [target]   # Quick overview (1 agent, ~2 min)
/learn [target]          # Standard (3 agents, ~5 min)
/learn --deep [target]   # Deep dive (5 agents, ~10 min)

Directory Structure

目录结构

ψ/learn/
├── .origins             # Manifest of learned repos (committed)
└── owner/
    └── repo/
        ├── origin       # Symlink to ghq source (gitignored)
        ├── repo.md      # Hub file - links to all sessions (committed)
        └── YYYY-MM-DD/  # Date folder
            ├── 1349_ARCHITECTURE.md      # Time-prefixed files
            ├── 1349_CODE-SNIPPETS.md
            ├── 1349_QUICK-REFERENCE.md
            ├── 1520_ARCHITECTURE.md      # Second run same day
            └── ...

Multiple learnings: Each run gets time-prefixed files (HHMM_), nested in date folder.

Offload source, keep docs:

bash

unlink ψ/learn/owner/repo/origin   # Remove symlink
ghq rm owner/repo                  # Remove source

ψ/learn/
├── .origins             # Manifest of learned repos (committed)
└── owner/
    └── repo/
        ├── origin       # Symlink to ghq source (gitignored)
        ├── repo.md      # Hub file - links to all sessions (committed)
        └── YYYY-MM-DD/  # Date folder
            ├── 1349_ARCHITECTURE.md      # Time-prefixed files
            ├── 1349_CODE-SNIPPETS.md
            ├── 1349_QUICK-REFERENCE.md
            ├── 1520_ARCHITECTURE.md      # Second run same day
            └── ...

多次探索：每次探索生成的文件都会带有时间前缀（HHMM_），并存放在对应日期的文件夹中。

卸载源码，保留文档：

bash

unlink ψ/learn/owner/repo/origin   # Remove symlink
ghq rm owner/repo                  # Remove source

Docs remain in ψ/learn/owner/repo/

undefined

undefined

/learn --init

Restore all origins after cloning (like

git submodule init

bash

ROOT="$(pwd)"

克隆仓库后恢复所有origin链接（类似

git submodule init

）：

bash

ROOT="$(pwd)"

Read .origins manifest and restore symlinks

while read repo; do ghq get -u "https://github.com/$repo" OWNER=$(dirname "$repo") REPO=$(basename "$repo") mkdir -p "$ROOT/ψ/learn/$OWNER/$REPO" ln -sf "$(ghq root)/github.com/$repo" "$ROOT/ψ/learn/$OWNER/$REPO/origin" echo "✓ Restored: $repo" done < "$ROOT/ψ/learn/.origins"

undefined

undefined

Step 0: Detect Input Type + Resolve Path

步骤0：检测输入类型 + 解析路径

bash

date "+🕐 %H:%M %Z (%A %d %B %Y)"

CRITICAL: Capture ABSOLUTE paths first (before spawning any agents):

bash

ROOT="$(pwd)"
echo "Learning from: $ROOT"

IMPORTANT FOR SUBAGENTS: When spawning Haiku agents, you MUST give them TWO literal paths:

SOURCE_DIR (where to READ code) - the
```
origin/
```
symlink
DOCS_DIR (where to WRITE docs) - the parent directory, NOT inside origin/

⚠️ THE BUG: If you only give agents

origin/

path, they cd into it and write there → files end up in WRONG repo!

FIX: Always give BOTH paths as LITERAL absolute values (no variables!):

Example: ROOT=/home/user/ghq/.../my-oracle, learning acme-corp/cool-library, TODAY=2026-02-04, TIME=1349:

READ from:  .../ψ/learn/acme-corp/cool-library/origin/
WRITE to:   .../ψ/learn/acme-corp/cool-library/2026-02-04/1349_[FILENAME].md

Tell each agent: "Read from [SOURCE_DIR]. Write to [DOCS_DIR]/[TIME]_[FILENAME].md"

bash

date "+🕐 %H:%M %Z (%A %d %B %Y)"

关键注意事项：优先捕获绝对路径（在启动任何Agent之前）：

bash

ROOT="$(pwd)"
echo "Learning from: $ROOT"

对子Agent的重要提示：启动Haiku Agent时，必须为其提供两个明确的路径：

SOURCE_DIR（代码读取路径）-
```
origin/
```
符号链接
DOCS_DIR（文档写入路径）- 父目录，不能在origin/内部

⚠️ 常见错误：如果仅向Agent提供

origin/

路径，它们会进入该目录并在其中写入文件 → 导致文件存入错误的仓库！

修复方案：始终提供两个明确的绝对路径（不要使用变量！）：

示例：ROOT=/home/user/ghq/.../my-oracle，正在探索acme-corp/cool-library，TODAY=2026-02-04，TIME=1349：

READ from:  .../ψ/learn/acme-corp/cool-library/origin/
WRITE to:   .../ψ/learn/acme-corp/cool-library/2026-02-04/1349_[FILENAME].md

请告知每个Agent：“从[SOURCE_DIR]读取代码，将文档写入[DOCS_DIR]/[TIME]_[FILENAME].md”

If URL (http* or owner/repo format)

若输入为URL（http*或owner/repo格式）

Clone, create docs dir, symlink origin, update manifest:

bash

undefined

克隆仓库、创建文档目录、生成符号链接、更新清单文件：

bash

undefined

Replace [URL] with actual URL

URL="[URL]" ROOT="$(pwd)" # CRITICAL: Save current directory! ghq get -u "$URL" &&
GHQ_ROOT=$(ghq root) &&
OWNER=$(echo "$URL" | sed -E 's|.github.com/([^/]+)/.|\1|') &&
REPO=$(echo "$URL" | sed -E 's|.*/([^/]+)(.git)?$|\1|') &&
mkdir -p "$ROOT/ψ/learn/$OWNER/$REPO" &&
ln -sf "$GHQ_ROOT/github.com/$OWNER/$REPO" "$ROOT/ψ/learn/$OWNER/$REPO/origin" &&
echo "$OWNER/$REPO" >> "$ROOT/ψ/learn/.origins" &&
sort -u -o "$ROOT/ψ/learn/.origins" "$ROOT/ψ/learn/.origins" &&
echo "✓ Ready: $ROOT/ψ/learn/$OWNER/$REPO/origin → source"


**Verify:**
```bash
ls -la "$ROOT/ψ/learn/$OWNER/$REPO/"

Note: Grep tool doesn't follow symlinks. Use:
rg -L "pattern" ψ/learn/owner/repo/origin/


**验证**：
```bash
ls -la "$ROOT/ψ/learn/$OWNER/$REPO/"

注意：Grep工具不会跟随符号链接。请使用：
rg -L "pattern" ψ/learn/owner/repo/origin/

Then resolve path:

然后解析路径：

bash

undefined

bash

undefined

Find by name (searches origin symlinks)

find ψ/learn -name "origin" -type l | xargs -I{} dirname {} | grep -i "$INPUT" | head -1

undefined

find ψ/learn -name "origin" -type l | xargs -I{} dirname {} | grep -i "$INPUT" | head -1

undefined

Scope

适用范围

For external repos: Clone with script first, then explore via

origin/

For local projects (in

specs/

ψ/lib/

): Read directly

外部仓库：先通过脚本克隆，再通过

origin/

路径进行探索 本地项目（位于

specs/

、

ψ/lib/

）：直接读取

Step 1: Detect Mode & Calculate Paths

步骤1：检测模式 & 计算路径

Check arguments for

--fast

--deep

```
--fast
```
→ Single overview agent
```
--deep
```
→ 5 parallel agents
(neither) → 3 parallel agents (default)

Calculate ACTUAL paths (replace variables with real values):

TODAY = YYYY-MM-DD (e.g., 2026-02-04)
TIME = HHMM (e.g., 1349)
REPO_DIR = [ROOT]/ψ/learn/[OWNER]/[REPO]/
DOCS_DIR = [ROOT]/ψ/learn/[OWNER]/[REPO]/[TODAY]/   ← date folder
SOURCE_DIR = [ROOT]/ψ/learn/[OWNER]/[REPO]/origin/  ← symlink
FILE_PREFIX = [TIME]_                               ← time prefix for files

Example:
- ROOT = /home/user/ghq/github.com/my-org/my-oracle
- OWNER = acme-corp
- REPO = cool-library
- TODAY = 2026-02-04, TIME = 1349
- DOCS_DIR = .../ψ/learn/acme-corp/cool-library/2026-02-04/
- Files: 1349_ARCHITECTURE.md, 1349_CODE-SNIPPETS.md, etc.

⚠️ CRITICAL: Create symlink AND date folder FIRST, then spawn agents!

Run the clone + symlink script in Step 0 FIRST
Capture TIME:
```
date +%H%M
```
(e.g., 1349)
Create the date folder:
```
mkdir -p "$DOCS_DIR"
```
Capture DOCS_DIR, SOURCE_DIR, and TIME as literal values
THEN spawn agents with paths including TIME prefix

Multiple runs same day? Each run gets unique TIME prefix → no overwrites.

检查参数中是否包含

--fast

或

--deep

：

```
--fast
```
→ 启动单个概览Agent
```
--deep
```
→ 启动5个并行Agent
无上述参数 → 启动3个并行Agent（默认模式）

计算实际路径（将变量替换为真实值）：

TODAY = YYYY-MM-DD (e.g., 2026-02-04)
TIME = HHMM (e.g., 1349)
REPO_DIR = [ROOT]/ψ/learn/[OWNER]/[REPO]/
DOCS_DIR = [ROOT]/ψ/learn/[OWNER]/[REPO]/[TODAY]/   ← date folder
SOURCE_DIR = [ROOT]/ψ/learn/[OWNER]/[REPO]/origin/  ← symlink
FILE_PREFIX = [TIME]_                               ← time prefix for files

Example:
- ROOT = /home/user/ghq/github.com/my-org/my-oracle
- OWNER = acme-corp
- REPO = cool-library
- TODAY = 2026-02-04, TIME = 1349
- DOCS_DIR = .../ψ/learn/acme-corp/cool-library/2026-02-04/
- Files: 1349_ARCHITECTURE.md, 1349_CODE-SNIPPETS.md, etc.

⚠️ 关键注意事项：先创建符号链接和日期文件夹，再启动Agent！

先执行步骤0中的克隆+符号链接脚本
捕获当前时间：
```
date +%H%M
```
（例如：1349）
创建日期文件夹：
```
mkdir -p "$DOCS_DIR"
```
将DOCS_DIR、SOURCE_DIR和TIME捕获为明确的真实值
然后启动Agent，路径中需包含时间前缀

当日多次执行探索？ 每次执行都会获得唯一的时间前缀 → 不会覆盖现有文件。

Mode: --fast (1 agent)

模式：--fast（1个Agent）

Single Agent: Quick Overview

单个Agent：快速概览

Prompt the agent with (use LITERAL paths, not variables!):

You are exploring a codebase.

READ source code from: [SOURCE_DIR]
WRITE your output to:   [DOCS_DIR]/[TIME]_OVERVIEW.md

⚠️ IMPORTANT: Write to DOCS_DIR (the date folder), NOT inside origin/!

Analyze:
- What is this project? (1 sentence)
- Key files to look at
- How to use it (install + basic example)
- Notable patterns or tech

Skip to Step 2 after agent completes.

向Agent发送如下提示（请使用明确的路径，不要使用变量！）：

You are exploring a codebase.

READ source code from: [SOURCE_DIR]
WRITE your output to:   [DOCS_DIR]/[TIME]_OVERVIEW.md

⚠️ IMPORTANT: Write to DOCS_DIR (the date folder), NOT inside origin/!

Analyze:
- What is this project? (1 sentence)
- Key files to look at
- How to use it (install + basic example)
- Notable patterns or tech

Agent完成任务后跳至步骤2。

Mode: Default (3 agents)

模式：默认（3个Agent）

Launch 3 agents in parallel. Each prompt must include (use LITERAL paths!):

READ source code from: [SOURCE_DIR]
WRITE your output to:   [DOCS_DIR]/[TIME]_[filename].md

⚠️ IMPORTANT: Write to DOCS_DIR (the date folder), NOT inside origin/!

并行启动3个Agent。每个提示必须包含（请使用明确的路径！）：

READ source code from: [SOURCE_DIR]
WRITE your output to:   [DOCS_DIR]/[TIME]_[filename].md

⚠️ IMPORTANT: Write to DOCS_DIR (the date folder), NOT inside origin/!

Agent 1: Architecture Explorer →

[TIME]_ARCHITECTURE.md

Agent 1：架构探索者 →

[TIME]_ARCHITECTURE.md

Directory structure
Entry points
Core abstractions
Dependencies

目录结构
入口文件
核心抽象
依赖关系

Agent 2: Code Snippets Collector →

[TIME]_CODE-SNIPPETS.md

Agent 2：代码片段收集者 →

[TIME]_CODE-SNIPPETS.md

Main entry point code
Core implementations
Interesting patterns

主入口代码
核心实现
有趣的设计模式

Agent 3: Quick Reference Builder →

[TIME]_QUICK-REFERENCE.md

Agent 3：快速参考文档构建者 →

[TIME]_QUICK-REFERENCE.md

What it does
Installation
Key features
Usage patterns

Skip to Step 2 after all agents complete.

项目功能
安装方法
核心特性
使用模式

所有Agent完成任务后跳至步骤2。

Mode: --deep (5 agents)

模式：--deep（5个Agent）

Launch 5 agents in parallel. Each prompt must include (use LITERAL paths!):

READ source code from: [SOURCE_DIR]
WRITE your output to:   [DOCS_DIR]/[TIME]_[filename].md

⚠️ IMPORTANT: Write to DOCS_DIR (the date folder), NOT inside origin/!

并行启动5个Agent。每个提示必须包含（请使用明确的路径！）：

READ source code from: [SOURCE_DIR]
WRITE your output to:   [DOCS_DIR]/[TIME]_[filename].md

⚠️ IMPORTANT: Write to DOCS_DIR (the date folder), NOT inside origin/!

Agent 1: Architecture Explorer →

[TIME]_ARCHITECTURE.md

Agent 1：架构探索者 →

[TIME]_ARCHITECTURE.md

Directory structure & organization philosophy
Entry points (all of them)
Core abstractions & their relationships
Dependencies (direct + transitive patterns)

目录结构与组织理念
所有入口文件
核心抽象及其关系
依赖关系（直接依赖+传递依赖模式）

Agent 2: Code Snippets Collector →

[TIME]_CODE-SNIPPETS.md

Agent 2：代码片段收集者 →

[TIME]_CODE-SNIPPETS.md

Main entry point code
Core implementations with context
Interesting patterns & idioms
Error handling examples

主入口代码
带上下文的核心实现
有趣的设计模式与编程技巧
错误处理示例

Agent 3: Quick Reference Builder →

[TIME]_QUICK-REFERENCE.md

Agent 3：快速参考文档构建者 →

[TIME]_QUICK-REFERENCE.md

What it does (comprehensive)
Installation (all methods)
Key features with examples
Configuration options

项目全面功能介绍
所有安装方式
带示例的核心特性
配置选项

Agent 4: Testing & Quality Patterns →

[TIME]_TESTING.md

Agent 4：测试与质量模式分析 →

[TIME]_TESTING.md

Test structure and conventions
Test utilities and helpers
Mocking patterns
Coverage approach

测试结构与规范
测试工具与辅助函数
模拟（Mocking）模式
代码覆盖率方案

Agent 5: API & Integration Surface →

[TIME]_API-SURFACE.md

Agent 5：API与集成面分析 →

[TIME]_API-SURFACE.md

Public API documentation
Extension points / hooks
Integration patterns
Plugin/middleware architecture

Skip to Step 2 after all agents complete.

公开API文档
扩展点/钩子
集成模式
插件/中间件架构

所有Agent完成任务后跳至步骤2。

Step 2: Create/Update Hub File ([REPO].md)

步骤2：创建/更新枢纽文件([REPO].md)

markdown

undefined

markdown

undefined

[REPO] Learning Index

Source

Origin: ./origin/
GitHub: https://github.com/$OWNER/$REPO

Origin: ./origin/
GitHub: https://github.com/$OWNER/$REPO

Explorations

[TODAY] [TIME] ([mode])

[[YYYY-MM-DD/HHMM_ARCHITECTURE|Architecture]]
[[YYYY-MM-DD/HHMM_CODE-SNIPPETS|Code Snippets]]
[[YYYY-MM-DD/HHMM_QUICK-REFERENCE|Quick Reference]]
[[YYYY-MM-DD/HHMM_TESTING|Testing]]
[[YYYY-MM-DD/HHMM_API-SURFACE|API Surface]]

Key insights: [2-3 things learned]

[[YYYY-MM-DD/HHMM_ARCHITECTURE|Architecture]]
[[YYYY-MM-DD/HHMM_CODE-SNIPPETS|Code Snippets]]
[[YYYY-MM-DD/HHMM_QUICK-REFERENCE|Quick Reference]]
[[YYYY-MM-DD/HHMM_TESTING|Testing]]
[[YYYY-MM-DD/HHMM_API-SURFACE|API Surface]]

Key insights: [2-3 things learned]

[TODAY] [EARLIER-TIME] ([mode])

...

undefined

...

undefined

Output Summary

输出摘要

--fast mode

markdown

undefined

markdown

undefined

📚 Quick Learn: [REPO]

Mode: fast (1 agent) Location: ψ/learn/$OWNER/$REPO/[TODAY]/[TIME]_*.md

File	Description
[REPO].md	Hub (links all sessions)
[TODAY]/[TIME]_OVERVIEW.md	Quick overview

undefined

Mode: fast (1 agent) Location: ψ/learn/$OWNER/$REPO/[TODAY]/[TIME]_*.md

File	Description
[REPO].md	Hub (links all sessions)
[TODAY]/[TIME]_OVERVIEW.md	Quick overview

undefined

Default mode

markdown

undefined

markdown

undefined

📚 Learning Complete: [REPO]

Mode: default (3 agents) Location: ψ/learn/$OWNER/$REPO/[TODAY]/[TIME]_*.md

File	Description
[REPO].md	Hub (links all sessions)
[TODAY]/[TIME]_ARCHITECTURE.md	Structure
[TODAY]/[TIME]_CODE-SNIPPETS.md	Code examples
[TODAY]/[TIME]_QUICK-REFERENCE.md	Usage guide

Key Insights: [2-3 things learned]

undefined

Mode: default (3 agents) Location: ψ/learn/$OWNER/$REPO/[TODAY]/[TIME]_*.md

File	Description
[REPO].md	Hub (links all sessions)
[TODAY]/[TIME]_ARCHITECTURE.md	Structure
[TODAY]/[TIME]_CODE-SNIPPETS.md	Code examples
[TODAY]/[TIME]_QUICK-REFERENCE.md	Usage guide

Key Insights: [2-3 things learned]

undefined

--deep mode

markdown

undefined

markdown

undefined

📚 Deep Learning Complete: [REPO]

Mode: deep (5 agents) Location: ψ/learn/$OWNER/$REPO/[TODAY]/[TIME]_*.md

File	Description
[REPO].md	Hub (links all sessions)
[TODAY]/[TIME]_ARCHITECTURE.md	Structure & design
[TODAY]/[TIME]_CODE-SNIPPETS.md	Code examples
[TODAY]/[TIME]_QUICK-REFERENCE.md	Usage guide
[TODAY]/[TIME]_TESTING.md	Test patterns
[TODAY]/[TIME]_API-SURFACE.md	Public API

Key Insights: [3-5 things learned]

undefined

Mode: deep (5 agents) Location: ψ/learn/$OWNER/$REPO/[TODAY]/[TIME]_*.md

File	Description
[REPO].md	Hub (links all sessions)
[TODAY]/[TIME]_ARCHITECTURE.md	Structure & design
[TODAY]/[TIME]_CODE-SNIPPETS.md	Code examples
[TODAY]/[TIME]_QUICK-REFERENCE.md	Usage guide
[TODAY]/[TIME]_TESTING.md	Test patterns
[TODAY]/[TIME]_API-SURFACE.md	Public API

Key Insights: [3-5 things learned]

undefined

.gitignore Pattern

.gitignore 规则

For Oracles that want to commit docs but ignore symlinks:

gitignore

undefined

对于希望提交文档但忽略符号链接的Oracle：

gitignore

undefined

Ignore origin symlinks only (source lives in ghq)

Note: no trailing slash - origin is a symlink, not a directory

ψ/learn/**/origin


**After running /learn**, check your repo's `.gitignore` has these patterns so docs are committed but symlinks are ignored.

ψ/learn/**/origin


**执行/learn后**，请检查仓库的`.gitignore`是否包含上述规则，确保文档被提交而符号链接被忽略。

Notes

注意事项

```
--fast
```
: 1 agent, quick scan for "what is this?"
Default: 3 agents in parallel, good balance
```
--deep
```
: 5 agents, comprehensive for complex repos
Haiku for exploration = cost effective
Main reviews = quality gate
```
origin/
```
structure allows easy offload
```
.origins
```
manifest enables
```
--init
```
restore

```
--fast
```
：1个Agent，适用于快速扫描“这是什么项目？”的场景
默认模式：3个Agent并行执行，平衡效率与深度
```
--deep
```
：5个Agent，适用于复杂仓库的全面探索
使用Haiku Agent进行探索更具成本效益
主审核环节为质量把关
```
origin/
```
结构支持轻松卸载源码
```
.origins
```
清单文件支持通过
```
--init
```
恢复链接