Yan's rulings, tradeoffs, and the reasoning behind them. Append-only. Durable rules graduate to the spec/principles docs directly (and get a pointer back here for the reasoning) — this file keeps the why, the canonical docs keep the what.
parent: [[CLAUDE.md]] · see also: [[LOG.md]] (current state) · [[JOURNAL.md]] (how the ruling came about)
Ruling: every non-trivial claim gets checkable L-form on first presentation — in chat and
in notes — not just once an entry is marked in-progress. Graduated to P14 (hard rule) in
AI-human mathematical collaboration principles.md.
Reasoning (Yan's own words): "If you just state a result, this will be hard for me to base on because on one hand, I cannot verify it immediately, and it looks right, on the other hand, it is not sure enough." The danger is specifically in territory the human isn't fluent in — that's exactly where a plausible-but-wrong claim is hardest to catch, so it's the last place a shortcut should be allowed, not a place where speed matters more.
2026-07-07 — citations need exact line numbers; pixel-precise highlighting is available but optional
Ruling: every *Source:* line quoting a physical book cites exact line numbers
(H p.117, ll.31–39), not just page + proposition number. A pdftotext -bbox-based technique
exists to build exact-highlight rect= links instead, and is documented in USER MANUAL.md,
but is not mandatory — line numbers are the required floor, highlighting is an upgrade path
when it's worth the extra step.
Reasoning: the exact-line requirement came directly out of a misquote that slipped past a
vaguer page-level citation (see JOURNAL.md). The highlighting technique was explored further
(session on 2026-07-08) and worked technically, but Yan's call after seeing it in practice:
"we don't have to do it, your text is already convenient enough" — i.e. the marginal
precision of a click-to-highlight link wasn't worth the extra pdftotext round-trip for
routine citation work. Kept as documented, optional tooling rather than a new hard rule.
Ruling: when a formatting bug (here: inline — [ ] Lk checkboxes not rendering as real
Markdown task items) is traced to the template in math-framework-spec.md rather than to one
note's mistake, fix the template, not just the note that surfaced it.
Reasoning: implicit in how the fix was actually applied — Yan's bug report was about one
note, but the root cause was the spec's own example. Recorded as a standing practice: a
symptom in one note is a prompt to check whether the template needs fixing before patching
the instance. (See JOURNAL.md's lessons wall for the general form of this.)