surgical-github-extraction

name	surgical-github-extraction
description	Use when user references GitHub repo as inspiration, not dependency — phrases like "look at this repo", "borrow from X", "use approach from Y", "implement like Z", or GitHub URL handed in as reference. Prevents clone or install. Fetches raw files to tempdir, lifts minimum useful snippet or concept, adapts to user project style. Output version-independent, dep-free.

Surgical GitHub Extraction

Why

Clone or install = version coupling + transitive deps + scaffolding buries concept. User usually want idea, not framework. Lift small, own it.

Use when

• User pastes GitHub URL + says "look at" / "borrow" / "use approach from" / "implement like".
• User want concept/architecture/technique from repo.
• User want small util lifted from bigger lib.
• Lib unmaintained, niche, or painful to install.

Skip when

• User says "install X" / "add to package.json".
• Lib = runtime engine (Next, React, FastAPI).
• Repo = CLI tool to run, not learn from.

Rules

1. Raw files, never clone. raw.githubusercontent.com/<o>/<r>/<sha>/<path> or gh api.
2. Tempdir, not project tree. Unix ${TMPDIR:-/tmp}/sge-<repo>-<sha>/. Win $env:TEMP\sge-<repo>-<sha>\.
3. Pin SHA, not branch. Future re-read need exact version.
4. README first. Then 1–3 source files for wiring. README = what, source = how. Stop once enough to adapt.
5. Minimum unit. Smallest function / prompt / config that solve need.
6. Adapt, not transplant. Match project conventions. Drop unused branches. Swap imports for stdlib or local utils.
7. Cite source. // adapted from github.com/<o>/<r>@<sha>:<path>.

Workflow

1. Clarify. One question max. Concept vs code lift? What's the one thing?
2. Fetch README via raw URL. Get shape.
3. Pin SHA once, reuse for all fetches.
4. List tree only if README don't point at right files.
5. Fetch 1–3 target files to tempdir — prompts, schemas, wiring.
6. Read, extract, adapt. Rewrite inline to project style. Drop dead code.
7. Paste + cite with provenance comment.
8. Verify. Run project typecheck/lint/test. Tempdir = scratch, never commit.

Two paths

• Concept-only: README + few key files for shape (agent defs, prompts, graph wiring). Propose analogue in user stack. Tempdir inspected, nothing committed.
• Surgical lift: README + target file. Extract minimum unit, adapt, paste with provenance. No pip install, no submodule.

Anti-patterns

• ❌ git clone into project or home dir.
• ❌ pip install git+https://... or npm install <tarball> when user want to learn from repo.
• ❌ Fetch all of /src "just in case".
• ❌ Paste verbatim with upstream imports and style intact.
• ❌ Pin main not SHA.
• ❌ Commit tempdir paths in scripts.

Quick reference

README       → curl -fsSL raw.githubusercontent.com/<o>/<r>/<sha>/README.md
tree         → gh api repos/<o>/<r>/git/trees/<sha>?recursive=1
one file     → curl -fsSL raw.githubusercontent.com/<o>/<r>/<sha>/<path>
pin SHA      → gh api repos/<o>/<r>/commits/<branch> --jq .sha | cut -c1-7
tempdir unix → ${TMPDIR:-/tmp}/sge-<repo>-<sha>/
tempdir win  → $env:TEMP\sge-<repo>-<sha>\
provenance   → // adapted from github.com/<o>/<r>@<sha>:<path>