# Mo Dev

> Develop and validate MatrixOne kernel changes with design-first gates, first-principles invariants, risk-proportional evidence, deterministic UT/BVT, and repository-specific CGo, operator/pipeline, planner, and index-plugin workflows. Use for MatrixOne production or test changes, bug fixes, feature/refactor design, kernel CI failures/hangs, and implementation review.

- Skill: `matrixorigin/mo-dev` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add matrixorigin/mo-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixorigin/mo-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: matrixorigin (https://skillmd.com/u/matrixorigin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/matrixorigin/mo-dev

---


Compatibility: designed for Codex CLI and compatible agents on supported
MatrixOne development platforms. Use the Go version in `go.mod`. CGo work also
requires the repository-supported compiler and matching native artifacts.

## Outcome and core workflow

Produce the smallest general change that restores or introduces an explicit
contract, then prove every affected boundary with the cheapest valid evidence.
Rigor is coverage of contracts and unhappy paths, not diff size, command count,
or repeated full-suite runs.

1. **Resolve scope once.** Record base, head, merge-base, committed plus local
   changes, and untracked/delivery artifacts. Build the change map and per-closure
   R0-R3 classification from
   [validation-evidence.md](references/validation-evidence.md).
2. **Classify design work.** Apply the feature/major-refactor gate before
   implementation. Ordinary focused bug fixes are exempt from a design document,
   but never from invariant, ownership, cost, or validation reasoning.
3. **State the contract.** Write the problem evidence, invariant and negation,
   first owner, affected consumers, state transitions, unhappy paths, and
   performance/resource budget before choosing the patch.
4. **Load only applicable domain references.** Use the resource map below; do
   not load or restate every specialized workflow.
5. **Implement the narrowest complete closure.** Change the common ownership or
   protocol boundary, not one observed trace. Update consumers/reverse arcs and
   tests in the same functional unit.
6. **Validate by information value.** Reuse semantically valid evidence, run the
   cheapest discriminating checks first, and escalate only along mapped risk
   dimensions. Do not rerun equivalent author/CI work.
7. **Review and deliver.** Run `mo-self-review` on the final scope, resolve every
   blocker, inspect the delivery diff, and report the compact evidence record.

For tests and diagnostic probes, acquire each resource only after its preceding
step succeeds and schedule its cleanup immediately in the same lexical scope.
When a loop performs repeated queries or opens rows/statements, use a small
helper or per-iteration closure so `defer` releases the resource before the
next iteration; a cleanup call at the bottom of a test is not equivalent on an
early assertion failure.

For diagnosis-only requests, stop after proving and explaining the cause; do not
turn diagnosis into an implementation without authorization.

## Resource map

Read a reference when its trigger applies:

| Need | Read |
|---|---|
| Change/risk map, efficient validation order, CI/local evidence reuse | [references/validation-evidence.md](references/validation-evidence.md) |
| Credible shared-state/lifecycle/synchronization/timing failure mode | [references/race-validation.md](references/race-validation.md) |
| Large/complex feature or major refactor; design document review (RFC optional) | [references/feature-design-review.md](references/feature-design-review.md) |
| UT/BVT purpose, orthogonality, fixture reuse, cost/flakiness, result and execution evidence | [references/testing-contract.md](references/testing-contract.md) |
| CGo compile/link/load/module errors, local wrapper, hang attribution, clean-baseline proof, GPU/cuVS/CUDA | [references/cgo-build-test.md](references/cgo-build-test.md) |
| `colexec`/`process`/pipeline lifecycle, typed terminal signals, distributed dispatch/receiver hangs | [references/operator-pipeline.md](references/operator-pipeline.md) |
| Planner/explain/rewrite correctness, public reachability, independent black-/white-box oracles | [references/counterexample-testing.md](references/counterexample-testing.md) |
| Vector/fulltext algorithm registry, build-tag registration, ISCP/CDC and index-plugin review | [references/index-plugin.md](references/index-plugin.md) |

## Enforcement gates

| Gate | Trigger | Required action |
|---|---|---|
| **G-FEATURE-DESIGN** | Feature/major refactor reaches the size threshold or any complexity trigger | Read the design contract; require and review an approved, versioned design document before implementation. A failed/missing design makes the review decision `REQUEST_CHANGES`; submit that GitHub review only when the task authorizes the mutation. |
| **G-CHANGE-MAP** | Before non-trivial implementation, validation, or review | Build one complete change map. Every changed hunk and contract must be covered; deep work is routed per closure rather than repeated over the whole diff. |
| **G-TEST-CONTRACT** | Production behavior changes or any UT/BVT is added, changed, removed, merged, or optimized | Read the testing contract. Map behavior to UT/BVT, inventory existing cases/fixtures, preserve all distinct oracles, and reject unnecessary data, sleeps, processes, or setup. |
| **G-CGO** | A selected package is CGo-direct/transitive, native/module/link/load errors occur, or GPU mode is involved | Read the CGo reference and use the controlled wrapper/appropriate GPU workflow. Diagnose the failing layer; do not change product code to mask environment failure. |
| **G-OPERATOR** | Editing/reviewing `colexec`, process signals, pipeline spool/protocol, or a distributed pipeline hang | Read the operator/pipeline reference before editing or concluding. Trace sender and receiver plus reset/cleanup terminal paths. |
| **G-COUNTEREXAMPLE** | Planner/explain/rewrite correctness or scenario-overfit risk | Read the counterexample reference. Define invariant/negation/reachability and use independent public and typed oracles where each proves a distinct claim. |
| **G-INDEXPLUGIN** | Index algorithm dispatch/plugin/registry/ISCP paths change | Read the index-plugin reference and its review section. New SQL/catalog per-algorithm dispatch is forbidden. |
| **G-STATIC-INCREMENTAL** | Any Go source/test edit or SCA failure | Derive the changed package closure from the merge base (including local staged/unstaged files), run gofmt/vet/lint only for that closure first, and escalate to the full repository scan only under the rules below. |
| **G-CI-TRIAGE** | A CI job fails, hangs, is cancelled, or is unexpectedly skipped | Capture the exact job step, SHA, platform/toolchain, and terminal result; classify code/static/test failure separately from network/cache/quota/disk/runner failure before changing code or deciding to rerun. |
| **G-EVIDENCE** | Before claiming pass/done or attributing a failure | Apply semantic evidence validity. Pending/empty selection/partial output is not a pass; a “pre-existing” claim requires the same failure at the verified clean baseline. |

## First-principles change rules

1. Start from the violated/missing invariant and the first owner of state or
   resources, not the proposed patch, issue spelling, or last stack frame.
2. Close success, error, cancellation, timeout, retry, partial initialization,
   reset/reuse, restart, and cleanup only where the mapped contract can reach
   them. Prove unreachable dimensions instead of testing them ritualistically.
3. Prefer deleting duplicated state/transitions/cleanup. Every new stateful
   component needs one effective owner, an explicit bound, admission/publication
   point, all terminal paths, and a generation/restart rule.
4. Keep mechanisms proportional. A local fix does not justify a framework,
   cache, worker, retry layer, global, extension point, or generic abstraction.
   Require multiple independent recurring needs, a stable contract, and lower
   total runtime/operational/testing/maintenance complexity.
5. Treat per-row/batch/message/transaction/query paths as hot until bounded.
   Account for allocations, copies, scans, synchronization, goroutines, I/O,
   logs, and metric cardinality; benchmark/profile only when cost can be
   material.
6. Avoid incident overfit. Do not encode issue IDs, one plan layout, exact data
   shape, or timing coincidence in production logic. Test the invariant,
   nearest control, and counterexample with minimum data and deterministic
   control.
7. Preserve user scope and permissions. Read-only review/diagnosis does not
   authorize production changes, GitHub review submission, or other external
   mutations.

## Efficient validation and completion

Use [validation-evidence.md](references/validation-evidence.md) as the source of
truth. In particular:

- prove exact package/test/case selection is non-empty;
- run focused evidence before broader owning-package/group evidence;
- validate a real consumer when an ownership/API boundary changes;
- add BVT/topology/restart/upgrade/race/GPU/performance only when the mapped
  contract requires that dimension;
- reuse exact-head CI or local evidence whose relevant semantic inputs and mode
  are unchanged; unrelated docs or PR metadata do not invalidate it;
- retain real terminal status and diagnose silence by polling the existing
  process, not by launching duplicates.

### Incremental static checks (default)

Do not run a repository-wide SCA for every edit. Resolve the merge base once,
include committed and local tracked/untracked Go files, inspect the resulting
package list, and run the configured checks only on that list:

```bash
set -euo pipefail
base_ref=${REVIEW_BASE:-origin/main}
merge_base=$(git merge-base HEAD "$base_ref")
tracked_go=$(git diff --name-only "$merge_base" -- '*.go')
untracked_go=$(git ls-files --others --exclude-standard -- '*.go')
changed_go=$(printf '%s\n%s\n' "$tracked_go" "$untracked_go" |
  sort -u | sed '/^$/d')
existing_go=$(printf '%s\n' "$changed_go" | while IFS= read -r file; do
  if [ -n "$file" ] && [ -f "$file" ]; then printf '%s\n' "$file"; fi
done)

if [ -n "$existing_go" ]; then
  format_files=$(printf '%s\n' "$existing_go" | xargs -r gofmt -l)
  if [ -n "$format_files" ]; then
    printf 'gofmt required for:\n%s\n' "$format_files" >&2
    exit 1
  fi
fi

changed_dirs=$(printf '%s\n' "$changed_go" | while IFS= read -r file; do
  if [ -n "$file" ]; then dirname -- "$file"; fi
done | sort -u)
changed_pkgs=$(printf '%s\n' "$changed_dirs" | while IFS= read -r dir; do
  if [ -z "$dir" ]; then continue; fi
  if [ ! -d "$dir" ]; then
    printf 'changed Go directory was removed; select affected consumers explicitly: %s\n' "$dir" >&2
    exit 1
  fi
  if ! find "$dir" -maxdepth 1 -type f -name '*.go' -print -quit | grep -q .; then
    printf 'changed Go directory has no current Go files; select affected consumers explicitly: %s\n' "$dir" >&2
    exit 1
  fi
  GOWORK=off go list -mod=readonly "./${dir#./}" || exit 1
done | sort -u)
if [ -n "$changed_go" ] && [ -z "$changed_pkgs" ]; then
  printf 'changed Go files exist, but no package was discovered\n' >&2
  exit 1
fi

if [ -n "$changed_pkgs" ]; then
  GOWORK=off go vet -mod=readonly $changed_pkgs
  GOWORK=off golangci-lint run -c .golangci.yml --new-from-rev "$merge_base" $changed_pkgs
fi
```

Use the CGo setup and wrapper from
[cgo-build-test.md](references/cgo-build-test.md) when the selected closure is
CGo-direct/transitive. Add directly affected consumers when an exported/API,
protocol, generated-code, or shared lifecycle contract changed; the package
list must not be a guessed single leaf. A deleted-only package directory must
stop this helper and be handled by explicitly selecting its existing consumers;
do not replace that decision with `./...`. If no Go file changed, run the
smallest checker for the changed artifact.

`make static-check-analysis`, `make static-check`, `golangci-lint run ./...`,
and equivalent whole-repository commands are the CI/full-scan path, not the
default edit loop. Escalate to one only when SCA configuration/toolchain or
workflow files changed, the affected consumer closure cannot be bounded, a
release/pre-push gate explicitly requires it, or a CI failure must be
reproduced. Record incremental and full results separately; a focused pass is
not evidence that full CI SCA is green. Never suppress a finding or delete
cleanup merely to make a static check pass.

### CI and environment diagnosis

When a CI check is red or silent, do not infer the cause from the check name or
partial output. Inspect the failing step and terminal log at the exact checked
SHA, then classify it before editing:

- **Code/static/test:** reproduce the smallest affected package/test locally
  with the same mode (race, coverage, tags, CGo, platform where possible), and
  fix the violated contract. Run static checks before an expensive cluster or
  end-to-end test.
- **Infrastructure:** network/API fetch failures, rate limits, unavailable
  caches, runner/toolchain setup, disk exhaustion, or a cancelled/evicted job
  do not by themselves prove a product failure. Preserve the log and classify
  the cancellation/eviction reason; rerun only a clearly transient job when
  authorized, and do not add sleeps, retries, skips, or product workarounds to
  hide it.
- **Ambiguous/hung:** keep the existing run as the source of truth; poll for a
  terminal result, inspect the process/stack and resource state, and avoid
  launching a duplicate service or test that can contend for ports, native
  artifacts, or global state. A timeout is evidence of a liveness failure until
  the wait-for path is explained.

For local native/integration work, preflight the selected toolchain, disk and
temporary directory, active test-owned processes/ports, and CGo artifact
provenance. Use the repository wrapper and an explicit temporary directory;
clean only artifacts owned by the test. Report environment failures separately
from code evidence, and never claim CI green from a pending, skipped, cancelled,
or unrelated check.

Ordinary pure-Go examples:

```bash
GOWORK=off go test -mod=readonly -list 'TestXxx' ./pkg/target
GOWORK=off go test -mod=readonly -v -count=1 -timeout 120s -run '^TestXxx$' ./pkg/target
GOWORK=off go test -mod=readonly -v -count=1 -timeout 120s ./pkg/target/...
GOWORK=off go vet -mod=readonly ./pkg/target/...
```

For CGo-direct/transitive packages, replace `go test` with:

```bash
.agents/skills/mo-dev/scripts/mo-cgo-test -count=1 -timeout=120s ./pkg/target/...
```

Before delivery, the record must show:

```text
□ resolved range/worktree scope and complete per-closure change map
□ design-gate decision and approved revision when triggered
□ invariant/root cause/owner/consumer and relevant unhappy paths closed
□ UT/BVT and specialized-domain decisions recorded
□ every required proof is validly reused or passed; gaps/pending work are explicit
□ generated/delivery artifacts, diff stat, and unintended files checked
□ `mo-self-review` has zero unresolved blockers
```

Never weaken assertions, add sleeps/retries/skips, broaden fixtures, or run an
unrelated package merely to make a checkbox green. Never claim “systematic”
from breadth alone: demonstrate one general contract closed across its relevant
state space with less total complexity than the credible alternatives.