repo-learningSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

# Chinese
我想深入学习 https://github.com/expressjs/express,目标是能提交 PR,每

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: repo-learning
description: Turn any code repository into a structured, trackable learning plan — overall approach, module-by-module breakdown, and a scheduled checklist. Use whenever the user wants to learn, study, understand, or deep-dive a codebase/repo/project, or asks for a 学习思路/学习计划/学习路线/怎么入手/读懂这个项目/codebase onboarding, or pastes a repo URL and asks how to approach it, or asks to break their repo learning into 番茄钟/打卡 tasks — even if they never say "learning plan". Also handles return sessions that punch in (打卡) or resume an existing LEARNING_PLAN.md.
---

# Repo Learning Plan

Turn a code repository into a learning plan the user can actually follow and track: an overall approach, a breakdown into units, and a scheduled checklist written to `LEARNING_PLAN.md`. The method is **pomodoro-paced and output-driven**: every unit is pre-split into 25-minute punch-card tasks (番茄拆解), every unit must end in a tangible artifact (输出物), and the whole plan ends in one capstone deliverable (毕业输出) — reading without producing does not count as done. The plan is a durable artifact — later sessions resume from the file, not from memory.

## Workflow

Five phases. Never skip Phase 0. For small repos, compress Phases 1–3 into one pass; for large ones, do them properly.

### Phase 0 — Scope the learning (before reading any code)

Plans fail when they optimize for the wrong goal. Establish four things in one batched round (AskUserQuestion works well, plain questions fine too):

1. **Goal** — contribute features? understand the architecture? take over maintenance? evaluate the tech? master one subsystem?
2. **Background** — familiarity with the language, the domain, and this repo already?
3. **Budget** — hours per week and total horizon ("1h/day for 3 weeks").
4. **Final output (毕业输出)** — what should exist when the plan is done? Suggest one from the goal: contributing → a merged PR; architecture mastery → a published technical blog post or a 20-minute talk; tech evaluation → a short written verdict with measurements. Never leave it undefined — a plan without a final output is just a reading list.

Pomodoro length defaults to 25 minutes; only ask about it if the user volunteers a preference.

If the user already supplied enough of this, state your assumptions in one sentence and move on. Never run a second round of questions unless an answer is impossible to proceed without.

### Phase 1 — Survey the repo

Read enough to see the skeleton, not every file. In order:

1. README, CONTRIBUTING, ARCHITECTURE/docs index, CHANGELOG
2. Project manifest(s): `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `pom.xml` ...
3. Directory tree, 2–3 levels deep
4. Entry points and build/run config (`main`, `cmd/`, `bin/`, Makefile, docker-compose, CI workflows)
5. Tests layout — test names reveal intended behavior better than source comments
6. Git history hot spots — files that change most are where the project's real complexity lives:

```bash
git log --since="1 year ago" --format= --name-only | sort | uniq -c | sort -rn | head -20
```

Per-ecosystem commands (LOC counts, dependency trees, import graphs) are in `references/survey-cheatsheet.md` — consult it when you need a command, don't run everything mechanically. If the repo isn't local yet, clone it first with `git clone --filter=blob:none` (keeps full history for hot-spot analysis without downloading everything). Never block the survey on a missing tool — fall back to reading the manifest and tree.

Keep the findings as a private scratch summary; do not dump raw survey output on the user:
- Tech stack and architecture style (monolith / services / library / plugin; framework; layering)
- Module map: major dirs → responsibility in one phrase each
- The **spine**: the one end-to-end flow that crosses the most of the codebase (e.g. HTTP request → router → middleware → handler → model → persistence → response)

### Phase 2 — Learning approach (整体思路)

Pick one strategy and justify it in one sentence:

| Strategy | When it fits |
|---|---|
| **Top-down** | Large codebase, architecture understanding is the goal: layers first, then modules, then files |
| **Trace-driven** | Contributing / feature work is the goal: follow the spine end-to-end, learn each module as the trace crosses it |
| **Bottom-up** | Small library or algorithm-heavy code: core data structures and utilities first |

For mid-size or larger repos, default to top-down for the first third of the plan, then switch to trace-driven — architecture without tracing stays abstract, tracing without architecture gets lost.

Write a 3–6 sentence narrative: how the repo is organized, what the spine is, why this walking order. This narrative opens the plan.

### Phase 3 — Break into units (内容拆分)

Split the content into 5–12 units. Each unit must be completable in one sitting's worth of pomodoros and must include a hands-on exercise — passive reading does not stick.

**Unit 0 is always "Run it"**: install deps, build, run the test suite, start the thing, trigger one real request. Nothing after this matters if the user cannot execute the code.

For every unit record:
- **Files** — real paths from the actual repo, ≤10 per unit. Never invent a path; if unsure, re-check the tree.
- **Concepts** — terms/patterns to look up ("middleware chain", "WAL", "how this repo does DI")
- **Exercise** — trace one request through the code, draw the module diagram, change something small and predict which test breaks, add a log line at each spine stage, write one test for an uncovered branch
- **Depends on** — prior unit ids
- **Estimate** — honest hours (2–8 typical), calibrated to *this user's* speed, not an expert's
- **番茄拆解** — 3–8 punch-card blocks; one verb-first task per block, sized to a single 25-minute pomodoro, each with a concrete done-criterion ("读完 `router/index.ts` 并画出 Layer/Route 关系图", never "了解 router"). Blocks × 25 min should roughly equal the estimate; a task that can't fit one pomodoro gets split, not s

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.