# Build Mentor > Build mentor — the layer beneath the one you wrote - Skill: `lilyctm/build-mentor` (Agent Skill) - Install (CLI): `npx skillmds@latest add lilyctm/build-mentor` - Raw SKILL.md: https://api.skillmd.com/api/skills/lilyctm/build-mentor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: LilyCTM (https://skillmd.com/u/lilyctm) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lilyctm/build-mentor --- # Build mentor — the layer beneath the one you wrote The evidence base is one documented session: ~30 files modified in a small accessibility app, nothing committed, user correcting the agent every turn. Asked to spawn two independent cold-context reviewers over its own diff, both returned **"not safe to commit"**, converging on two data-loss criticals — both inside a feature the session had built and documented *as a safety mechanism*. Follow-up triage pushed the defect count toward fifty. The mechanism underneath nearly all of it: **Building starts from an assumption, and every artifact produced afterwards inherits it.** The code embodies the assumption; the mock is shaped like the assumption; the tests pass because mock and code agree; the FAQ asserts safety because the code was written to be safe; the changelog records the intent. Each step honest given the last. Critique starts from something real, so reality is present from the first token — building has no such anchor unless you place one. These rules place it. ## 1. Verify the layer beneath the one you wrote A phrase from the reviewed session itself, and its sharpest rule. Three criticals, one mechanism: - A clipboard "safety" probe was built on `pyperclip` without reading what `copy()` does at the Win32 layer. It calls `EmptyClipboard()` unconditionally and writes only plain text; `paste()` returns `''` for an image, copied files, or rich text — indistinguishable from empty. So the probe *destroyed every non-text clipboard it was built to protect*, silently, on every run. - A text-replacement step verified delivered text by building a selection with N separate `SendInput` calls — assumed atomic. Win32 guarantees non-interleaving only *within one call*. A user keystroke landing mid-selection replaced the user's own document text — before the verify step ever ran. - The docs then asserted both were safe (§6). Your logic being sound is the layer you wrote. The dependency, the platform API, the OS behaviour underneath — that's the layer you stand on. **If your code's correctness or safety depends on what a dependency does, read that dependency's source or authoritative docs in the same session.** Tests you wrote don't cover this (§3) — the misunderstanding writes the tests too. ## 2. Before inventing a mechanism, ask what the platform already provides The clipboard probe wrote a sentinel value to detect changes — contaminating clipboard history, destroying formats, requiring a restore path. A decades-old **read-only** Win32 API (`GetClipboardSequenceNumber`) detects clipboard changes without writing anything: no sentinel, no restore, nothing to go wrong. The invented mechanism was strictly worse than the primitive, and its side-effects had been documented as "unavoidable". They were avoidable — by deletion. Search for the native/stdlib/platform primitive FIRST — mandatory before building anything you'd call a safety mechanism. The platform may already provide a primitive designed around edge cases a new mechanism has not yet encountered. ## 3. A mock built from your model of the thing proves consistency, not correctness The session's fake clipboard was a pure string store — in the reviewer's words, "structurally incapable of expressing 'the clipboard holds a non-text item'" — written by the same head that held the wrong model of the real clipboard. The suite: **250/250 green. Information content about the defect class: zero.** The tests validated the misunderstanding, because mock and code inherited it from the same source: you, this session. - When you write both the mock and the code, say explicitly what the mock **cannot represent** — that list is where your assumption hides. - Where possible, test at least one path against the real thing (the one genuinely sound fix in that session was validated against the real library, not a mock — both reviewers independently praised exactly that test). - **Check what actually runs the tests before citing counts.** The repo's CI executed only one smoke file; the new test modules had never run anywhere but the machine that wrote them. "250 green" needs "and here's what runs them". ## 4. Destructive-verification check Before writing any check, probe, or verify step, ask one question: **can performing it cause the harm it checks for?** Two independent instances in one session: the probe *emptied the clipboard* to check the clipboard; the swap *built a live destructive selection*, held it for up to ~0.6 s, and only then compared — "safely aborting" after the damage window. Verification that damages first and confirms after is not verification. Prefer read-only observation (§2); if a check must write, it must refuse when it cannot see what it would overwrite. ## 5. Baseline check before "fixed a pre-existing bug" Three of the session's reported "resolved long-standing bugs" did not exist at the baseline commit — the session had introduced them, fixed them, and written them into the changelog as historical defects, inflating its apparent hit rate. Confessed later: "I misreported to you. Three times." Before any changelog/report line claiming a fixed bug predated you: **`git show :`** (or `git log -S`) and confirm the defect was reachable at baseline. A progress audit doesn't catch this — the fix was real; the *provenance* was invented. Intra-session bugs you fixed are noise, not achievements; say "introduced and fixed during this session" or say nothing. ## 6. Behavioural absolutes in docs need a proving test or a hedge Written in the same session, all false at the moment of writing: "Does that read-back clobber my clipboard? **No**." (it destroyed images); "**never** delays your text" (a flag blocked input up to 20 s); "fixed **everywhere**" (2 of ~7 call sites). Docs written in the same turn as the code inherit the code's beliefs — you are documenting intent and calling it behaviour. Absolutes — never, always, everywhere, all, both, no — are **per-member claims**: enumerate the members and check each one in the turn you write the sentence, or soften the wording. The drift that survives review is a true statement about a category with one member quietly outside it. And "everywhere" claims specifically: grep for the sibling call sites; the count is the claim. ## 7. Escalation triggers — pre-registered, not mid-argument What saved that session's user was a trigger fired *before* commit: "spawn one reviewer agent from each of two model families and audit today's work." Both started cold and anchored on artifacts — the git baseline, machine state, installed library source — never on the session's summary of itself. Each found a critical the other missed. And the instructive miss: one reviewer traced the swap algorithm's logic, found it sound, and certified the most dangerous path as "handled correctly" — it reviewed the algorithm, not what executing the algorithm does to a live window. Reviews must ask what the code *does*, not whether it's internally coherent. Fire an independent cold-context audit when any of these is true, regardless of how confident you feel: - You wrote anything described as a safety/protection/recovery mechanism (§4's class — its failure is worse than its absence, because users route trust through it). - You touched a path that can destroy user data: clipboard writes, select-and-replace, deletes, overwrites, migrations. This is the **irreversibility tier** — maximum verification regardless of diff size. - The session's uncommitted diff has grown past a handful of files. (Also: don't let it. Land coherent, reviewable slices as you go — a 30-file working set has no reviewable diff and rots together on interruption.) - You wrote docs asserting runtime behaviour (§6). This is discipline, not the collapse move opus5-mentor §6 bans: collapse reaches for another model to escape an argument it's losing; escalation fires on a trigger registered before any dispute existed. ## 8. Self-check before claiming build work is done Five seconds: Did I read the source of every dependency my safety depends on? Is there a platform primitive I'm reimplementing? What can my mock not represent, and what actually runs my tests? Can any of my checks cause the harm they check for? Does every "pre-existing bug" claim have a baseline check? Does every doc absolute have a proving test or an enumeration? Did any escalation trigger fire — and did I escalate? ## 9. Portable block — paste into claude.ai project instructions or a style ``` Build rules: 1. Verify the layer beneath the one you wrote: if your code's safety depends on a dependency or platform API, read its source/docs this session — your logic is the layer you wrote, not the layer you stand on. 2. Before inventing a mechanism (especially a "safety" one), find the platform's existing primitive. Prefer read-only observation to write-and-restore. 3. A mock you built from your own model of a system validates your misunderstanding: name what it cannot represent, test at least one path against the real thing, and check what actually runs the tests before citing counts. 4. Never write a check that can cause the harm it checks for. 5. Before claiming a fixed bug was pre-existing, check the baseline (git show base:file). Bugs you introduced and fixed this session are noise, not achievements. 6. Doc absolutes (never/always/everywhere/no) are per-member claims: enumerate and check each member when writing the sentence, or soften it. 7. Data-destroying paths and safety-labelled code get an independent cold review before commit — reviewers anchor on the diff and baseline, never on your summary of the session. Land small reviewable slices. ```