docs: capture #2547's investigation/verification lessons - #2621
Merged
Conversation
… + ci-push-checklist Two friction points from fixing #2547 that cost real time/tokens, distinct from #2620's crucible_check.py env-drift hardening (a different issue, #2518): 1. No documented technique for empirically inspecting what detector.py actually extracted for a given file -- root-causing the #2547 bug required reading _slice_by_keywords/ _slice_by_terminator cold before realizing `galaxyscope --debug` + grepping the WORKER-TRACE log line is far cheaper. Added as its own CLAUDE.md section, cross-linked from the ci-push-checklist skill's "Local & Unit Validation" step. 2. CLAUDE.md's Differential Scan section told a reader to regenerate golden masters via `python tests/tools/update_golden_master.py` directly -- technically correct (it's the sanctioned mechanism) but misleading: it silently updates only whichever ONE fixture matches whatever's importable in the current shell, with none of crucible_check.py's venv/PATH automation. The better path (`crucible_check.py --update --yes`, which handles both modes through properly-scoped venvs) was already documented 10 lines below in the same section, just never cross-referenced -- reading the first instruction and stopping there (as I did) cost a full manual venv-wrangling cycle. Reordered so the automated entry point is what a reader hits first, with update_golden_master.py explained as the underlying single-mode script it wraps. Also noted (ci-push-checklist): Claude Code's Auto Mode classifier blocks blessing a golden master by default, even via --yes on a no-op clean tree -- worth expecting up front rather than hitting it as a surprise mid-task. Docs only, no code/fixture changes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two documentation gaps found while fixing #2547, distinct from #2620's
crucible_check.pyenv-drift hardening (that came out of a different issue, #2518):No documented technique for empirically inspecting what
detector.pyextracted. Root-causing orphan census counts non-function shapes on non-call-graph languages, making orphan→api conversion unauditable #2547 required tracing_slice_by_keywords/_slice_by_terminatorcold before realizinggalaxyscope --debug+ grepping the[WORKER-TRACE] extracted functions forlog line shows the exact satellite/function names directly. Added as its own CLAUDE.md section, cross-linked from theci-push-checklistskill.CLAUDE.md's Differential Scan section pointed at the wrong entry point first. It told a reader to regenerate golden masters via
python tests/tools/update_golden_master.pydirectly — technically correct, but that only updates whichever ONE fixture matches whatever's importable in the current shell, with none ofcrucible_check.py's venv/PATH automation. The better path (crucible_check.py --update --yes, handles both modes automatically) was already documented 10 lines below in the same section — just never cross-referenced. I read the first instruction, ran it, and paid for a full manual venv-wrangling cycle (discovered via--help, hand-exportedPATH, hand-ranpip install -e . --no-deps) before finding the better path. Verified the fix empirically:crucible_check.py --update --yes --mode bothon a clean tree handles both venvs with zero manual bookkeeping (confirmed "No drift detected" for both modes with no PATH/pip commands from me).Also noted in
ci-push-checklist: Claude Code's Auto Mode classifier blocks blessing a golden master by default, even via--yeson a no-op clean tree — worth expecting up front.Docs only, no code or fixture changes.
🤖 Generated with Claude Code