| name | nexus-testing |
| description | Verify a Nexus change — pick a Jest lane, write a test that can actually fail, run the in-app Obsidian CLI loop, drive the eval harness, or fix a shipped-docs drift failure. Use when adding or changing tests, when a mock might be deciding the outcome, when a change has to be proven in the running plugin, or when the guidance gate fails. |
Testing Nexus
Context: every Jest lane resolves obsidian to a hand-written mock — see
moduleNameMapper in jest.config.js. A green suite therefore proves the code
agrees with tests/mocks/obsidian/, not with Obsidian. Three ranking defects
shipped past that suite. Everything below exists to close the gap between what
Jest can prove and what the running plugin does.
Workflow
-
Pick the job and open its protocol. Work from the protocol, not from this
router — the router names procedures, it does not contain them.
| Job | Protocol |
|---|
| Add or change a test | protocols/write-a-test.md |
| Prove a change works in the running plugin | protocols/live-loop.md |
| No Obsidian here (container / cloud session) | protocols/headless-obsidian.md |
| Run a gated live-smoke lane or the eval harness | protocols/run-gated-lanes.md |
shippedGuidanceCommands or ToolManagerCliSyntax is red | protocols/fix-shipped-docs-drift.md |
| Merge a PR (what to run first, how to gate on CI) | protocols/merge-a-pr.md |
| A symptom you cannot place | references/troubleshooting.md |
-
Derive every list from the tree, never from a document. This skill states no
test counts, no lane inventory and no env-var table on purpose, and you MUST
NOT add one — those rot silently and a rotted list is worse than none.
references/lanes.md holds the discovery commands.
-
Before calling a testing change done, run both checks from the repo root and
fix anything they print:
python3 .claude/skills/nexus-testing/scripts/check_live_lane_gates.py
python3 .claude/skills/nexus-testing/scripts/check_catalog_target.py
-
NEVER claim a change is verified in the app on the strength of Jest alone.
If the change touches load order, rendering, hydration or anything that only
exists once the plugin is running, protocols/live-loop.md is the proof and
nothing else is.
-
At the end of a session that used this skill, run protocols/self-refine.md.
Map
protocols/ the procedures: write-a-test, live-loop, headless-obsidian,
run-gated-lanes, fix-shipped-docs-drift, self-refine.references/ read on demand: lanes.md (where a test goes and how to find
what exists), mock-honesty.md (the two habits that make a test able to fail),
troubleshooting.md (symptom → cause).scripts/ the mechanical checks named in step 3. Run them; do not
reimplement them.refinement-log.md what past sessions changed here and why.
Siblings — do not duplicate them here
nexus-eval-harness — configuring, extending and debugging the eval harness.
This skill covers only running it and the two knobs that surprise people.nexus-model-eval — grading specific models.nexus-tool-schemas — regenerating the tool catalog (no running vault needed).nexus-agents — the two-tool contract and the useTools payload shape a test
has to build.nexus-mobile-compat — the mobile failure class the in-app loop cannot see.nexus-storage — resetting persisted state when a plugin reload is not enough.
Status of the in-app loop
Exercised 2026-08-14 against Obsidian 1.13.7 in a headless Linux container
and 2026-08-21 against Obsidian 1.12.7 on macOS. Setup, vault-targeted
plugin:reload, dev:errors, dev:console, dev:screenshot, dev:debug, and
synchronous eval are confirmed working. The first run found a startup-ordering
bug that every Jest lane was blind to; the macOS run confirmed explicit
vault=<name> targeting and clean repeated reloads.
