From 4559a1adc35569ab3ce74ff32ec41b925c75545f Mon Sep 17 00:00:00 2001
From: Nicholas Butzke <137417822+DottsGit@users.noreply.github.com>
Date: Sun, 26 Jul 2026 12:47:42 -0400
Subject: [PATCH] =?UTF-8?q?docs(skill):=20record=20why=20Miku=20has=20no?=
 =?UTF-8?q?=20cloth=20=E2=80=94=20the=20source=20had=20no=20skeleton?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two shipped characters are a controlled comparison: Taila's source
arrived rigged (35 cloth chains, 8 twist bones, 18 meshes, artist
weights), Miku's did not (5 meshes, 0 joints), so Miku was auto-rigged
into one mesh with nearest-bone weights and no cloth chains at all. Her
twin tails and skirt are dead geometry and the destructive load-time
weight repair runs on her every spawn.

None of that is recoverable downstream, which makes picking a source that
already has skirt and hair bones the highest-leverage decision in the
pipeline. Added the no-Blender check for vetting a candidate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../references/separation.md                  | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/.claude/skills/character-pipeline/references/separation.md b/.claude/skills/character-pipeline/references/separation.md
index 46bbddb..77b85d7 100644
--- a/.claude/skills/character-pipeline/references/separation.md
+++ b/.claude/skills/character-pipeline/references/separation.md
@@ -97,6 +97,42 @@ guesses.
    tracks onto them (`keep_anim_armature`), the AnimationPlayer overwrites the
    spring solver every frame.
 
+## Worked example: why the two shipped characters differ so much
+
+Both are in `assets/characters/skins/`. Compare their sidecars:
+
+| | Taila | Miku |
+|---|---|---|
+| source had a skeleton | yes | **no — 5 meshes, 0 joints** |
+| `weights_authored` | true | **false** |
+| cloth chains | 35 (127 bones) | **0** |
+| twist bones | 8 | **0** |
+| meshes shipped | 18 | **1** |
+
+Miku's source (`assets/characters/incoming/miku_test.glb`) is an unrigged mesh,
+so she went through `autorig.py`: joined to one mesh, rebound by nearest-bone
+weighting, no cloth chains. Her twin tails and skirt are dead geometry that
+cannot move, and `SkinLegRepair` runs destructively on her every spawn.
+
+Nothing downstream can recover this. **The single highest-leverage decision in
+this whole pipeline is choosing a source model that already has a skeleton with
+skirt and hair bones.** Everything else is recoverable; this is not.
+
+A quick check on any candidate, without Blender:
+
+```python
+import json, struct
+with open(path,'rb') as f:
+    f.read(12); clen,_=struct.unpack('<II',f.read(8))
+    j=json.loads(f.read(clen))
+nodes=[n.get('name','') for n in j['nodes']]
+joints=[nodes[i] for s in j.get('skins',[]) for i in s['joints']]
+print(len(j['meshes']), 'meshes', len(joints), 'joints')
+print([n for n in joints if any(t in n.lower() for t in ('hair','skirt','tail','ribbon'))])
+```
+
+Several meshes, 50+ joints, and a non-empty cosmetic list means a good source.
+
 ## Checking a source model before importing
 
 ```bash