docs(skill): record what four non-library rigs taught the role resolver

Names lie and anatomy does not — the four VRoid imports each broke role resolution differently, and the lesson generalises: anything guessing anatomy from a bone name needs a structural fallback. Also lists what is shipping and which characters have chains that do not simulate. Co-Authored-By: Claude Opus 5 <[email protected]>
2026-07-26 13:46:23 -04:00
parent fc9e6f4275
commit 2ce2175d99
2 changed files with 37 additions and 0 deletions
@@ -19,6 +19,31 @@ are `DEF-spine`, her head is `DEF-spine.006`, and she has **no bone with "neck"
 in its name at all** — unresolved, every lean, aim pitch and slide head-lift
 silently did nothing.

+### Names lie. Anatomy does not.
+
+Four sources that were not authored against the library's spelling each broke
+role resolution in a different way. All four fixes are in; the lesson is that
+**anything guessing anatomy from a name needs a structural fallback.**
+
+- A bare `leg` is the SHIN on Mixamo (`LeftUpLeg` is the thigh) and the THIGH on
+  a rig whose shin is called `knee`. Same token, opposite bones, both common. So
+  `RigRoles` walks the leg upward from the foot and fills in whatever the names
+  could not, stepping over twist bones.
+- Claims are granted **longest-stem first**. Taking the first role in
+  `LIMB_ORDER` that matched at all let shin's catch-all `"leg"` beat thigh's
+  exact `"upperleg"`, and the outcome depended on bone iteration order.
+- Cosmetic and spring classes accept a **two-character positional suffix**:
+  `HairFL`, `HairFR`, `HairF_Top` tokenise to `hairfl` and matched nothing, so a
+  character imported with no hair chains at all. Two characters is short enough
+  that `forearm` and `earring` are still not swept in.
+- VRoid spells legs `UpperLeg`/`LowerLeg`. Any CHECK that name-matches
+  `thigh`/`shin` will silently pass or silently fail on it — see
+  `verification.md`.
+
+If a new source fails with `could not identify these bones`, dump the joint names
+first (`separation.md` has a no-Blender snippet) and decide whether it is a
+missing stem or a case only anatomy can settle.
+
 ## Rebuilding the hierarchy

 A Rigify DEF-rig exports its chain roots parented straight to the armature root,