# Upstream Source Research

> ALWAYS LOAD THIS SKILL WHEN RESEARCHING AN UPSTREAM PACKAGE OR HOSTED REPOSITORY SUCH AS GITHUB OR GITLAB FOR SOURCE CODE, ISSUES, REFS, RELEASES, OR COMMIT HISTORY. Do not assume web-only research is enough before reading this skill.

- Skill: `quick-brown-foxxx/upstream-source-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add quick-brown-foxxx/upstream-source-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quick-brown-foxxx/upstream-source-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: quick-brown-foxxx (https://skillmd.com/u/quick-brown-foxxx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/quick-brown-foxxx/upstream-source-research

---


# Upstream Source Research

Decide first whether ordinary web research is enough or whether the task should escalate.

## Default Approach

- Start with the smallest viable method.
- Prefer hosted views and web fetches for short lookups.
- Switch to `gh`, `glab`, or another relevant CLI when you need better access to issues, PRs, release metadata, tags, or repository navigation.
- Use a shallow clone into `/tmp` when you need local source inspection, fast code search, commit history, or broader reading across many files.
- Keep the goal narrow: inspect and extract conclusions, not set up a long-lived checkout unless the task truly needs one.

## When To Escalate Beyond Web

- The answer depends on real source code across multiple files.
- You need issue, PR, tag, branch, or release data that is awkward or incomplete via web fetches.
- Browser, fetch, or API calls are hitting rate limits or other access limits.
- The investigation is large enough that repeated web requests are slower or noisier than local inspection.
- You need repository-wide search, blame, or commit-level context.

## Tool Choice

- Prefer `gh` for GitHub and `glab` for GitLab when available.
- Prefer non-interactive CLI commands that return focused data.
- Prefer lightweight remote inspection such as `git ls-remote` when refs or tags are enough.
- Prefer shallow clones such as `--depth 1` unless history is part of the question.
- Deepen incrementally with `git fetch --deepen` or a larger `--depth` only if the investigation proves more history is needed.
- Clone into `/tmp` by default for temporary inspection work.
- Avoid turning research checkouts into project dependencies or permanent local state unless the user asks.

## Temporary Clone Hygiene

- Treat `/tmp` clones as disposable research artifacts.
- If the clone needs submodules, deeper history, or large assets, keep checking whether that extra weight is actually required.
- By default, schedule deletion of each temporary upstream source tree for two wall-clock hours after active inspection ends. Use a systemd timer or a safe native equivalent; prefer a **user-scoped** timer (`systemctl --user` / `systemd-run --user`), which needs no sudo and does not trigger a global password prompt. If scheduling is unavailable or fails, state clearly that cleanup is **not scheduled**.
- Scope deletion to the exact full tree path beneath the OS temporary dir. Avoid deleting incorrect dirs and any empty, broad, or non-temporary path; never use globs or broad deletion commands.
- Report the target, cleanup mechanism, trigger time and timezone, and cancellation procedure. If the user wants to preserve the tree, do not schedule cleanup or cancel/drop the timer or job and confirm the tree remains.

## Return Value

Return the useful conclusion, the evidence source, and any constraints discovered during research.

If you used a temporary clone, mention where it was created and its cleanup status, including the scheduled mechanism/time and cancellation command when applicable.

## Avoid

- Cloning by habit when one or two web reads would answer the question.
- Fetching full history when shallow history is enough.
- Leaving temporary research source trees behind without telling the user.
- Treating rate-limit friction as a blocker before trying better-suited CLIs or a local clone.