Study Sources

Study sources

Ground your work in real upstream source rather than recalled API shapes. When a task turns on how a library, framework, or SDK actually behaves — its exact function signatures, its edge cases, an error string, a private helper, a version-specific change — read the source. This skill maps where each ecosystem already keeps readable source on disk, and how to fetch it into .scratch/ when it isn't local yet.

Two habits make this reliable:

1. Read what's installed before you clone. Most ecosystems cache decompressed source locally — node_modules/, ~/.m2, the Gradle/Cargo/NuGet/Go caches, the Android SDK's sources/. Reading the version the project actually resolved is faster and more correct than cloning main, which may be ahead of the pinned release.
2. Everything fetched lands in .scratch/. This directory is gitignored (repo-wide), so cloned repos and unpacked archives never pollute the working tree, git status, or the project's history. Keep one sub-folder per source, e.g. .scratch/sources/<ecosystem>/<name>@<version>/.

Guardrails

• Read-only. This skill fetches source to study. Do not build, install, run, or execute anything you pull in — you are reading code, not adopting a dependency.
• .scratch/ only. Never clone or unpack into the project tree. If .scratch/ is not already ignored, add it to .gitignore before fetching (do not fetch into a tracked path). Confirm with git check-ignore .scratch when unsure.
• Prefer the resolved version. Match what the project's lockfile / build resolved, not the latest tag, unless the user explicitly wants upstream HEAD.
• Shallow and narrow. Clone with --depth 1 and, for large monorepos, a sparse or blobless checkout (see references/git-sources.md). You want the code to read, not the full history.
• Network is a fallback. Reach the network only when the source isn't already on disk. In sandboxed/offline runs, exhaust local caches first and tell the user if a fetch needs network access.

The universal workflow

1. Name the target. Which package/repo, and — critically — which version? Read the project's lockfile or manifest to resolve it (package-lock.json/pnpm-lock.yaml, requirements.txt/poetry.lock, pom.xml/*.gradle, go.mod, Cargo.lock, *.csproj, Gemfile.lock, composer.lock, pubspec.lock, Package.resolved).
2. Check the local cache first. Use the map below to look where that ecosystem already stores decompressed source. If it's there, read it in place — no fetch.
3. Fetch into .scratch/ if missing. Use the ecosystem's own "download source" path (source JARs, pip download, go mod download, cargo vendor, npm pack, etc.), or clone the Git repo at the matching tag. Land it under .scratch/sources/….
4. Read narrowly. Grep for the symbol, type, or string you need. Note the file:line and the exact version you read, so any claim you make is traceable.

Ecosystem cache map — look here before fetching

If $ARGUMENTS opens with a Git URL, treat it as a clone request → git-sources.md. If it names a package@version or an ecosystem keyword, route to that ecosystem's reference. Otherwise infer the ecosystem from the project's manifests and the map above.

When NOT to use this

• The answer is already in the project's own tree — read that first.
• The library's public docs fully cover the question and version drift isn't a risk (still prefer source for exact signatures and edge cases).
• You'd be fetching just to run or build it — that's a dependency-adoption task, not a study task; this skill only reads.