Add mcore-determinism-debug skill

[ZhiyuLi-Nvidia]

Two runs of a deterministic recipe that disagree give one number to work from: the iteration where the loss curves split. That is where the difference grew large enough to print, not where it started. This skill documents the method that answers which op first diverged.

The method: run the job twice, fingerprint every op into a rank-local ordered stream, diff the two streams offline. The first record whose output differs while its inputs matched is the root cause -- everything before it matched byte for byte, so no hypothesis is needed, and forming one before that record is in hand is the most common way these investigations go wrong.

SKILL.md carries the method: the capture ladder (loss curve -> semantic boundaries -> ATen ops -> targeted probe -> below the dispatcher), the multi-arm repro harness, how to read a first divergence, and how to turn a site into a mechanism with a discriminator table.

references/tracing-setup.md covers arming the tracer: the capture layer, the call-site lifecycle, cost controls, read-only-container injection, and the hash function. references/reading-traces.md covers the three ways a correct trace yields a wrong conclusion -- the one-hop-later rule for kernels that bypass the dispatcher, known probe artifacts, and digest semantics.

On hashing, the guidance is to use torch.hash_tensor and not design there: it is far faster than a hand-written position-weighted digest and allocates no measurable scratch, where the custom digest needs three times the input tensor in temporaries. Its one real gap is permutations -- xor over any permutation of 0..n-1 is identically zero, so routing maps and MoE dispatch outputs are invisible when reduced whole-tensor. The fix is granularity, not a different hash: hash_tensor takes dim=, and chunked reduction costs the same as whole-tensor while catching any permutation that crosses a granule.

Benchmark constants are deliberately left out of the docs. They came from one GPU and one torch build; the ordering is the durable result.

• I, the PR author, have personally reviewed every line of this PR.

What does this PR do?

⚠️ For major changes (either in lines of code or in its impact), please make sure to first share a design doc with the team. If you're unsure what's the best way to do so, contact @NVIDIA/mcore-oncall.

Issue tracking

For PRs from open-source community contributors:

• New features: a linked issue is required. Please open a feature request and reference it here before submitting the PR.
• Small updates (bug fixes, minor improvements): a linked issue is recommended and will accelerate the PR review process.

Linked issue:

Contribution process

Pre-checks

• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code Typing guidelines
• I have added relevant documentation
• I have run the autoformatter.sh on my PR

Code review

Feel free to message or comment @NVIDIA/mcore-oncall to help accelerate your merge into main. The less complex your PR is, the faster it will be approved and merged!

All PRs start as draft. If you open a non-draft PR, it will be automatically converted to draft.

Step 1: Mark PR as "Ready for Review"

1. When your PR is ready, click Ready for Review.
2. An oncall reviewer is auto-assigned and expert reviewers are notified based on your changes.
   • Some PRs may jump straight to step 2. This is determined by .github/CODEOWNERS.

⚠️ Only mark as ready once merge-conflicts are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

Step 2: Final Review

For PRs that change megatron/core, once all expert reviewers have approved, the Final Review label is applied automatically and final reviewers are assigned.

For PRs outside megatron/core, this step is skipped.

Step 3: Approved

Once all required reviewers have approved, the Approved label is applied automatically.

Merge

Any member of mcore-engineers will be able to merge your PR.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

This PR has been automatically converted to draft because all PRs must start as drafts.

When you are ready for review, click Ready for Review to begin the review process. This will:

1. Add the oncall reviewer (optional reviewer)
2. Add required review teams based on your changes

See the contribution guide for more details.