3779b5c · hypercore-kb

hypercore-kb commits / 3779b5c

skills/deep-debugging: walk the layers bottom-up, and check each "why"

Adds section 2.1b, from a correction made mid-session: walk the abstraction
layers one by one from the foundations up, and at every point check whether the
proof you have matches how you would explain "why" to a human. If it does not,
assert the underlying facts at the LOWER level and compose or lift them.

Written because this session produced the textbook failure twice. "The shader
must be fine because the map loads and the log is clean" is reasoning at the top
layer; the fact at the bottom was a duplicate global declaration that never
compiled. And a headless repro was allowed to stand in for a GPU symptom without
checking the two were the same failure -- they were not, and the GPU measurement
falsified the whole theory (87.9 us against the working generator's 252.7 us).

Includes the corollary that instruments are layers too: before believing a
measurement that contradicts your model, prove the instrument gives a KNOWN
result on a KNOWN-GOOD input. An instrument that reports the same number for
every input is not evidence, it is a broken ruler. Also earned this session --
grep silently reported nothing on a log containing NUL bytes, and that was read
as "the log says nothing" rather than "my tool is lying".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

3779b5c75cc969b2877dc1b9cc35b0417c0a9217

by plankatron <fleeky@gmail.com> · 2026-08-30T23:54:21.000Z

Changed files (1) +32 -0

.claude/skills/deep-debugging/SKILL.md +32 -0

…	…	@@ -58,6 +58,38 @@ Module System
58	58	Native/System
59	59	```
60	60
	61	### 2.1b Walk the Layers Bottom-Up, and Check Each "Why" Against a Human
	62
	63	Walk the abstraction layers one by one from the foundations all the way to the
	64	top. At every point, see if the proof you have matches how you would explain
	65	"why" to a human. If it does not, assert the underlying facts at the LOWER
	66	level and compose or lift them upward.
	67
	68	This is the antidote to the most expensive failure mode in practice: a chain of
	69	plausible-sounding reasoning where one link is asserted rather than
	70	established. If you cannot say "X is true because I measured it at layer N",
	71	then X is a guess wearing the clothes of a fact, and everything you build on it
	72	inherits that.
	73
	74	Concretely, at each layer ask:
	75
	76	- What do I KNOW here, and what did I merely infer from the layer above?
	77	- Could I state this fact to someone as "here is the proof", or only as
	78	"here is my reasoning"?
	79	- If only reasoning: stop climbing. Go down, establish the fact directly, and
	80	then lift it.
	81
	82	A worked failure: "the shader must be fine because the map loads and the log is
	83	clean" is reasoning at the top layer. The fact at the bottom layer was that the
	84	assembled shader string had a duplicate global declaration and never compiled.
	85	No amount of care at the top would have found it; only dumping the actual
	86	string and running the actual compiler did.
	87
	88	The corollary is that instruments are layers too. Before believing a measurement
	89	that contradicts your model, prove the instrument produces a KNOWN result on a
	90	KNOWN-GOOD input. An instrument that reports the same number for every input is
	91	not evidence, it is a broken ruler.
	92
61	93	### 2.2 Locate the Failure Point
62	94	Which layer is actually failing? Don't assume!
63	95