Menu
Fast recipes for answering when/what/why a feature, flag, API, file, or string was added, removed, unflagged, or renamed in git history.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
This project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.
Build and test nub during development. Invoke (via the Skill tool) whenever you need to compile the dev `nub` binary, set up a worktree for fast incremental iteration, run a specific test file or a single test, or get oriented in the codebase (the crate map). Encodes the measured fast-build loop: the `fast` profile + one stable per-worktree target dir gives a ~3-min cold build then ~5s incremental rebuilds; a shared cross-worktree compile cache (sccache) was measured to give 0% Rust speedup and is NOT used. Covers the real incantations (`cargo build -p nub-cli --profile fast`, `make install-dev`, `make addon-fast`), the test invocations, and the exact CI cheap gates.
Verify new nub functionality end-to-end by building the dev binary and exercising it against a real throwaway fixture. Invoke (via the Skill tool) after implementing or changing a subcommand/flag/behavior, to confirm the feature ACTUALLY works (not just that tests pass). The loop: create a fixture in a tmp dir, build the dev `nub`, run the subcommand you implemented against the fixture, verify it had the intended effect, then run command variants to probe edge cases. Ad-hoc e2e is a valid verification method on its own; this skill also covers when to promote a durable check into the committed test suite. Pairs with the `dev-loop` build skill and AGENTS.md's pre-push loop.
Create and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the stable per-worktree CARGO_TARGET_DIR fast loop, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.
End-to-end playbook for working a GitHub issue (or bug-fix PR) on nubjs/nub: triage → acknowledge an external report with an "Investigating" comment → reproduce and fix (via the fray methodology + the pre-push local-verification loop) → open a PR that references the issue with `Closes #N` → on merge, comment the resolution → on release, comment the version + release link. Invoke (via the Skill tool) whenever you pick up an issue to work, or are asked to fix a reported bug. Encodes the maintainer-hygiene conventions in AGENTS.md so the reporter is acknowledged, the issue is auto-closed by the merge, and the loop is closed when the fix ships.
Pull jdx/aube's latest upstream changes into nub's plain-vendored `vendor/aube/**` with the fewest merge-conflict iterations. Invoke (via the Skill tool) whenever you need to bring a new upstream aube release (or arbitrary jdx/aube commits) into nub. Encodes the post-Pattern-B model: the vendored tree is plain in-tree files (NO git submodule, NO pin) and has no merge-base with jdx/aube, so a naive overwrite would be a conflict mess. The blessed path uses `nubjs/aube` `nub-fork` (which DOES carry real upstream ancestry, merge-base with jdx) as the 3-way merge venue, then brings the merged tree into `vendor/aube` via a delta-apply that preserves any in-tree fixes. Covers the merge-not-rebase rule, ours-wins conflict resolution, the nub-fork drift reconciliation, and the build/test gates.
| name | git-archaeology |
| description | Fast recipes for answering when/what/why a feature, flag, API, file, or string was added, removed, unflagged, or renamed in git history. |
Instant playbook for "when did X land / leave / change?" questions. The goal: skip the meander, get the answer in one command.
# All commits that changed the COUNT of <string> in a path:
git log --oneline -S'<string>' -- <path>
# First introduction (oldest commit):
git log --oneline --reverse -S'<string>' -- <path> | head -1
# Most recent change:
git log --oneline -S'<string>' -- <path> | head -1
# Include all branches:
git log --oneline --all -S'<string>' -- <path>
Use when: finding the commit that added or removed an exact symbol, flag string, function name, or config key. -S counts occurrences — it fires when the count changes.
git log --oneline -G'<regex>' -- <path>
Use when: -S misses a change because the string appears in both old and new (count unchanged), or when you want to match a pattern across added/removed lines (e.g. -G'--experimental-shadow-realm' to find every commit that touched that flag in any form).
# Find the commit that deleted a specific path:
git log --oneline --diff-filter=D -- <path>
# Find deletion of any file matching a name glob (across all branches):
git log --oneline --diff-filter=D --all -- '**/<name>'
# Cross-check the surrounding context:
git show <sha> -- <path>
Use when: a file exists in memory or docs but is absent from the tree — find when it was dropped and what the commit message says.
git log --follow --oneline -- <path>
Use when: a file was renamed and git log -- <path> shows a short history that obviously predates the file's true age.
# History of lines matching a pattern (N lines from match):
git log -L'/<pattern>/',+<N>:<file>
# History of a fixed line range:
git log -L<start>,<end>:<file>
Use when: tracing exactly when a specific function body, feature flag block, or config stanza was introduced or changed — avoids reading the whole file log.
# Full diff scoped to a path:
git show <sha> -- <path>
# Summary of what the commit touched:
git show --stat <sha>
Use when: you have a SHA from a pickaxe result and need to see the exact diff.
# Blame a line range:
git blame -L<start>,<end> <file>
# Blame + full patch context (expensive but thorough):
git log -p -L<start>,<end>:<file>
Use when: you need the author + date for specific lines, or want the full patch history for a code block.
git log -1 --format='%h %cs %s' <sha>
Use when: a pickaxe returned a SHA and you need the short date (%cs = YYYY-MM-DD) and subject without extra noise.
# In implementation code (crates/, runtime/):
git log --oneline --reverse -S'<string>' -- crates/ | head -1
# In marketing/docs (site/, README):
git log --oneline --reverse -S'<string>' -- site/ README.md | head -1
A gap between these two dates = the feature was advertised before (or after) it shipped. The code date is the authoritative answer to "when did it land."
site/, README.md, and docs may list a feature aspirationally from the initial commit. Searching there answers "when was it promised," not "when did it ship." To answer "is X implemented / when did it land?", pickaxe:
crates/ — Rust implementationcrates/nub-core/src/node/flags.rs and spawn.rs — flag injection (the authoritative source for "is a Node experimental flag active by default")Concrete burn: most homepage API names traced to "Initial commit" — all misleading, answered intent not state.
A positive pickaxe hit on site/ does not mean the feature ships today. Always run the delete check and a grep for "deferred"/"removed"/"dropped" before concluding it's live:
git log --oneline --diff-filter=D -- '<feature-file>'
git log --oneline --all --grep='deferred\|removed\|dropped' -- '<area>'
Concrete burn: connect() appeared on the homepage but runtime/connect-sockets.mjs was deleted 2026-05-26 and the feature deferred.
# Find all commits that touched experimental-flag injection:
git log --oneline -G'--experimental-' -- crates/nub-core/src/node/flags.rs crates/nub-core/src/node/spawn.rs
# Pickaxe a specific flag:
git log --oneline -S'--experimental-shadow-realm' -- crates/
Cross-reference .fray/*-unflag.md / audit threads for the decision record. This makes "what was recently unflagged?" instant rather than a multi-file meander.
Concrete answer this should make instant: shadow-realm + wasm-modules were unflagged together in PR #31.
| State | How to verify |
|---|---|
| On the homepage / in docs | Pickaxe site/, README |
| Implemented (code exists) | Pickaxe crates/, runtime/ |
| Unflagged / default-on | Pickaxe flags.rs, spawn.rs for the flag string |
Always check which state is actually being asked about before searching.
--all for deleted or branch-resident contentDeleted files and features that were developed on a branch and later dropped may only appear in non-main history. Add --all to any pickaxe or --diff-filter=D search when the expected result isn't turning up on main.
History rewrites change SHAs but not content — pickaxe by string still works after a force-push because it searches diff content, not commit identity.