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.