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.