Reference hunt

Reference Hunt

Sometimes the user cannot describe what they want in words — showing beats telling. The best reference is source code.

Workflow

1. Get a pointer. If the user already named a reference (a library, a vendored crate, a folder, a component on a website), start there. If not, propose 2-3 candidate references yourself — from the codebase, vendored dependencies, or well-known open-source implementations — and let the user pick. One short message, not an interview.
2. Read the real implementation. Locate the source in this order: node_modules/vendored copies inside the project → the package's repository at the installed version (npm view <pkg> repository or the ecosystem's equivalent, then fetch the tagged file) → GitHub code search (needs auth; anonymous fallback: shallow-clone the repo or fetch raw files by path from raw.githubusercontent.com). For a website module, read the underlying markup and code. Read the source, not its README, docs, or a screenshot. Also skim its test file — edge-case semantics (ordering, error paths, boundary values) live in tests more reliably than in the implementation body. A different language from the target is fine; semantics transfer, syntax does not. When the reference's framework differs from the target's, list which behaviors are carried by framework scheduling (pre-paint effects, batched updates, subscription timing) — re-create those deliberately; they neither transfer for free nor count as mere syntax.
3. Write down what you are taking. Before implementing, give the user a short list, in the language of the conversation: the semantics being ported and what is deliberately not being ported. Cover five dimensions: inputs/API shape, outputs and return values, state transitions, edge cases, failure behavior. The list must outlive the chat:
   • if implementation starts now, record the ported semantics under Context and your own deliberate deviations under Decisions in implementation-notes.md (per the implementation-notes skill);
   • otherwise write it to porting-checklist.md in the project root, headed by the reference name+version, then the five dimensions; if planning comes next, hand that file to implementation-plan as an input. Do not commit it unless the user asks; in a git repo, exclude it locally: n=porting-checklist.md; p="$(git rev-parse --git-path info/exclude 2>/dev/null)" && { mkdir -p "$(dirname "$p")" && { grep -qxF "$n" "$p" || echo "$n" >> "$p"; }; } 2>/dev/null || echo "note: could not exclude — leaving it untracked, never staging it"
4. Reimplement, don't transplant. Port the behavior into the target stack following the project's existing conventions and idioms. Cite the reference file paths — with version or commit for remote references (e.g. [email protected] debounce.js) — in your summary so claims are checkable.

When source is not readable

• Website with minified JS: check for sourcemaps first (look for a sourceMappingURL directive at the file tail, then confirm the .map actually loads); otherwise use the minified code only to confirm structure, and find an open-source implementation of the same pattern to read for semantics.
• Closed-source SaaS or nothing readable: first look for a well-known open-source implementation of the same pattern and read that as the semantic reference. Only when none exists, tell the user you are downgrading to black-box observation (drive the UI/API, record behavior as a table of input → output/state; if the behavior sits behind a login, ask the user for access or a screen recording), and mark ported semantics as "observed, not read".
• Reference too large to read fully: find the file that owns the core behavior (search for the distinctive algorithm/state names first), read it plus its direct tests — budget roughly 3-5 files; follow at most one import hop when the behavior clearly spans modules, and name what you skipped as "assumed standard".

Rules

• Never copy code verbatim from an external reference — port semantics and match the project's style. Check the reference's license first (LICENSE file, package.json, or npm view <pkg> license): permissive (MIT/Apache/BSD) is fine to port from with attribution in your summary. For GPL/AGPL, warn that reading the source then reimplementing risks a derivative work; if the user proceeds, extract semantics into the taking list first, implement only from the list without re-opening the source, and say so in the summary. For no license, warn that the default is all-rights-reserved and prefer a permissive alternative; black-box observation is the license-safe fallback.
• If the reference's behavior conflicts with something the user stated, surface the conflict instead of silently picking one.
• If the reference turns out to be a poor fit, say so and propose another.