thinking-kernel

name

thinking-kernel

description

Use when working in a technical domain with no existing playbook, writing new coding guidelines / review criteria / checklists from scratch, judging whether a verification method actually proves a claim (test passed but does it count?), or when repeated fixes keep failing and the direction feels wrong. Domain-agnostic reasoning moves that generate concrete decision criteria for any field — not tied to any language or framework.

🌐 繁體中文（canonical） · English mirror

Thinking Kernel: Seven Moves That Generate Criteria

Positioning: each domain playbook (android/ios/flutter/frontend-web/backend-server) is the "crystallized judgment"; this file is the "moves that produce those judgments." When you hit a domain or situation no playbook covers, don't wing it — run these seven moves and generate the criteria yourself. After generating, write them back into a playbook and add a matching quiz item in lockstep (rules and quizzes move together). The full cross-domain derivation table and an unfamiliar-domain worked example are in references/derivations.md.

Move 1: Grading Evidence Strength — "Does this verification actually prove this claim?"

Procedure: ① List the difference axes between the "verification environment" and the "environment the claim lives in" (compile mode, machine, data volume, concurrency, environment flags, time). ② If the claim falls on some difference axis, that verification's evidence strength is zero on it. ③ Swap in a verification that covers that axis, or state outright "this point is unverified." Derivation example: debug green ↛ release safe (R8 only takes effect in release); passed on one machine ↛ rolling-deploy safe (old and new coexist during the deploy window); simulator ↛ signing/entitlement (the simulator does no real signing). Applying to a new domain: first ask "what difference axes does this domain have" — each axis automatically spawns a batch of "X can't prove Y" criteria.

Move 2: Constructing the Failure Scenario — "What input/state → what bad outcome?"

Procedure: For any rule, coding pattern, or review comment, force-construct one concrete failure chain: "when [input/state], it will [bad outcome]." Constructible → it's a real problem, severity set by the bad outcome; not constructible → downgrade to a nit or delete it. Derivation example: "only log after catch" → when upload fails the user sees a forever-spinning spinner (real problem); "the naming here isn't elegant enough" → no failure chain constructible → nit. index as list key → deleting a row misaligns the checked state onto the wrong row. Applying to a new domain: this is the QC gate for reviews and rule-writing — a comment that can't state a failure scenario is not allowed onto the list.

Move 3: Adjudicability Test — "Bring three concrete scenarios: can you rule A or B?"

Procedure: After writing a candidate rule, construct three boundary scenarios to test it. If any one can't be adjudicated → add a numeric threshold, a count, or an explicit signal, until all three are adjudicable. A rule you can't adjudicate is the same as no rule. Derivation example: "keep components clean" (unadjudicable) → "extract only on the 3rd repetition of the same structure, when it needs its own test, or when it has its own state; tough out the 2nd" (adjudicable). "Introduce a UseCase when appropriate" → "create one only when used by ≥2 ViewModels, or when it composes ≥2 Repositories." Applying to a new domain: run every maxim in the domain ("keep it simple," "watch performance") through this test and rewrite it into an adjudicable version.

Move 4: Making Illegal States Unrepresentable — "Can this discipline become machine-enforced?"

Procedure: When you find a rule that "relies on someone remembering," move it up the enforcement ladder: type/schema > compiler/constraint > lint/CI > docs > verbal discipline (further left = more reliable). Only what can't be moved up stays at the docs layer — and ask why it can't. Derivation example: "loading and error are never both true" via discipline → a sealed type/AsyncValue makes the contradictory state unrepresentable; "check email duplication before registering" via check-then-insert → a DB unique constraint makes the duplicate unwritable; "UI state must be mutated on the main thread" via vigilance → a @MainActor type-layer annotation lets the compiler catch it. Applying to a new domain: list the three most-frequently-violated disciplines in the domain and ask each "how far up the ladder can it move?"

Move 5: Aligning Lifecycle and Ownership — "How long should it live? Who owns it? Where's the truth?"

Procedure: For any state, resource, or background job, answer three questions: ① how long should it live per the requirement ② who is responsible for creating and destroying it ③ is there exactly one place holding the "truth" of a given piece of information. The mechanism's lifecycle must equal the requirement's lifecycle — too long is a leak, too short is data loss. Derivation example: "the upload must continue after the screen closes" → can't use a screen-bound scope, and can't use an uncontrolled global (GlobalScope); inject an App-level scope. Remote data stored in a separate useState in many places → the truth is fragmented, switch to a single cache. ctx stored into a struct → outlives the request, wrong. Applying to a new domain: list every kind of resource in the domain (connection, temp store, cache, task) and answer the three questions for each; the ones you can't answer are future leak points.

Move 6: Whack-a-Mole Detection and Backtracking — "Is the hand wrong, or the upstream assumption?"

Procedure: When any signal appears: ① the same error fixed twice and still there (the fix is just a variant) ② each fix spawns a new one elsewhere ③ exception handling keeps piling up ④ you want to change the test/warning to shut it up → stop trying at the current layer, backtrack to the previous decision point, write out that layer's assumptions one by one and re-verify them, rather than offering a third fix. Derivation example: patching keep rules class by class, finishing one and the next blows up → go back to the rules layer and keep the whole model directory as one bundle; suppressHydrationWarning sprinkled ever more widely → go back to "what divergent value was read during render"; ANR rewritten three times and still there → measure first to find the real blocking point. Applying to a new domain: this move is domain-independent, use it as-is; the key is "which layer to backtrack to" — list the assumptions this path depends on and verify the most suspicious first.

Move 7: Asymmetric-Cost Tradeoff — "The cost of undoing a mistake vs. the cost spent upfront"

Procedure: Before acting, compare two numbers: A = the cost of undoing after a mistake (irreversible? blast radius?) B = the cost of upfront protection (ask one question, run one more verification, split into two steps). A ≫ B → do the protection, "it's a hassle" is not a reason; A ≈ B or reversible → just do it, don't over-ritualize. Derivation example: migration rename in one shot (A = a 500-storm across the deploy window) → prefer splitting into five steps over three releases; "should I ask the user first" → ask only when the two readings have high rework cost, don't ask about variable naming; premature abstraction (A = the cost of decoupling a wrong abstraction exceeds the duplication) → extract on the 3rd occurrence. Applying to a new domain: identify every irreversible operation in the domain (delete data, send externally, change a public contract) — those are where the protection budget should be spent.

Usage Flow (when you hit a domain with no playbook)

0. Pre-entry prep: before touching anything, dispatch a research agent to collect the domain's known pitfalls and conventions (official pitfalls, incident postmortems, release checklists) — pay the first-timer's tuition at a discount; feed the output into Moves 1–3 as raw material, it does not replace them.
1. Run Move 1 first: list the difference axes → get a draft "release must-check list" for the domain.
2. Run Move 5 next: list resources and state → get a draft of the architecture criteria.
3. Sweep the domain's maxims with Move 3 → rewrite the unadjudicable ones.
4. Pair each criterion produced with a failure scenario via Move 2, and ask via Move 4 whether it can be machine-enforced.
5. Write it up as a playbook (format per _meta/style-contract.md) + one quiz item for each high-risk criterion.

Honesty Clause (the part the kernel can't carry for you)

The seven moves can generate criteria, but the feel for the tradeoff (the weighting, taste, and aesthetics when multiple criteria conflict) cannot be documented. On a taste question: state your low confidence outright, give options with concrete examples and let the user choose, never fake certainty. Flagging uncertainty costs no points; fabricating does.