Tracking: dance UAT, ballet fidelity, notation interoperability, and choreography UX

[a-baran-orhan]

Summary

Track a detailed dance-focused UAT pass that exposed improvements needed across Posecode's documentation, language expressiveness, biomechanical configuration, ballet examples, spatial visualization, and product positioning.

This is an umbrella issue. It should be split into focused implementation issues after the design questions are triaged, while preserving this issue as the source of the complete user feedback and validation plan.

Why this matters

The feedback came from someone familiar with dance notation and ballet who spent a morning using the language rather than only watching the demo. They liked the core concept, readability, and "Mermaid for movement" framing, but found several places where the current system either hides important information, cannot express dance semantics, or renders examples that a trained dancer may reject as incorrect.

The strongest product signal is not necessarily "dancers will write Posecode or prompt an LLM." A more credible dance use case may be using Posecode underneath an interface for teaching, inspecting, scrubbing, varying, and communicating movements that an instructor can no longer demonstrate physically. The supplied example is a complex 540 movement.

Current-state findings

These points were verified against the current repository:

• The formal language specification exists at spec/SPEC.md, but it is not prominent enough in the authoring journey.
• The pasteable LLM guide is maintained separately in spec/llm-authoring.md and rendered to the public site. It overlaps heavily with the normative spec.
• pin, reach, ground-lock, and grip are documented, but the distinction is dense enough that a motivated first-time user still could not build a clear mental model.
• cue is represented in the IR, but the docs do not state prominently enough that it is user-facing coaching text and has no effect on solving or rendering.
• Start poses are a closed built-in vocabulary. Documents cannot define a custom pose or override selected channels of a built-in start pose.
• The current general ROM table caps hip external rotation at 45°, ankle dorsiflexion at 15°, and ankle plantarflexion at 50°.
• first-position seeds 30° hip external rotation on each side.
• The current examples are demi-plie.posecode, releve.posecode, pirouette.posecode, and chasse.posecode.
• The playground does not provide a strong visual floor reference for judging distance, path, or facing during travel and turn.
• Free flight is currently considered unsupported, which may prevent faithful representation of the supplied 540 example.

Workstream 1: make the language and authoring model discoverable

Canonical documentation structure

• Make the formal spec reachable within one click from the playground, authoring guide, movement pages, and the main README authoring section.
• State explicitly that spec/SPEC.md is normative and spec/llm-authoring.md is a task-oriented, pasteable authoring guide.
• Keep the pasteable guide self-contained. An LLM cannot be assumed to open a referenced spec URL, so reducing it to only a link is not sufficient.
• Add an automated parity check for closed vocabularies, grammar keywords, ROM examples, start poses, contacts, props, and timing modes so the spec and guide cannot silently drift.
• Where practical, generate shared tables or snippets from parser protocol constants instead of maintaining multiple hand-written copies.

Explain constraints by behavior, not only grammar

• Add a compact comparison table for the four contact mechanisms:
  • ground-lock: preserve an existing floor support
  • reach: move one limb endpoint toward a target through IK
  • pin: translate the whole body around one primary anchor
  • grip: dedicated one-hand or two-hand bar/rail contact
• Add one minimal valid example and one invalid/conflicting example for each mechanism.
• Add a visual or interactive example showing how the same requested contact behaves differently under reach and pin.
• Explain that root-solving families cannot be combined freely and show how to express additional contacts with reach.
• State directly in the grammar, guide, and UI that cue is display-only coaching text. It does not alter the pose, constraints, timing, validation, or renderer.
• Add capability and limitation links near the copy-prompt action so users know what the language cannot represent before prompting.

Documentation acceptance criteria

• A first-time user can find the normative spec without searching the repository.
• A first-time user can correctly predict whether pin or reach moves the body.
• No public documentation implies that cues influence animation.
• A test fails when the parser's closed vocabulary changes without corresponding authoring documentation.

Workstream 2: investigate custom and overridable start poses

The tester asked to define at least a custom start pose by overriding a built-in pose. This could make domain-specific starting positions readable without repeating them as an artificial first animation phase.

• Write a small language design proposal for start-pose overrides.
• Compare at least these options:
  1. An inline override block attached to pose start = first-position
  2. A reusable named pose declaration followed by pose start = <name>
  3. A zero-duration or non-animated setup phase in the IR rather than new grammar
• Define how overrides interact with ROM clamping, diagnostics, inherited channels, loop reset, share URLs, LSP completion, formatting, and older parsers.
• Ensure a base pose plus overrides remains visibly distinct from an animated step.
• Add parser, IR, timeline, LSP, playground, and round-trip tests for the selected design.

Suggested evaluation example: start in ballet first position with a domain-correct arm position without requiring a visible transition from arms-at-sides.

Workstream 3: support domain-aware movement ranges without weakening general validation

Do not simply replace the general ROM table with the largest ballet values. The tester supplied useful domain observations, but they should be verified with qualified sources and implemented as representation profiles or contextual constraints rather than universal safety claims.

Investigate ROM profiles and contact context

• Review hip external rotation for ballet. The current ceiling is 45°; the UAT suggestion is at least 60°, preferably up to 90° for the ballet representation.
• Review ankle dorsiflexion by context. The UAT suggestion is approximately 15° non-weight-bearing and up to approximately 30° weight-bearing.
• Review ballet plantarflexion. The current ceiling is 50°; the UAT suggestion for pointe-oriented representation is approximately 90° to 100°.
• Decide whether the model needs explicit profiles such as general and ballet, configurable rig limits, or solver context inferred from active contacts.
• Keep authored-angle validation and IK/contact constraints aligned under any profile.
• Keep the distinction between a representational ceiling and a medical or safety recommendation explicit.
• Avoid sex-based ROM profiles. If personalization is added later, prefer explicit rig/user configuration over broad male/female assumptions.

Ground-contact invariants

• Reproduce the Demi-plié heel lift with ground-lock: feet.
• Decide precedence when an authored pose, ROM clamp, and required contact cannot all be satisfied.
• A declared planted sole should either remain visibly planted or produce an explicit unresolved-contact diagnostic. It must not silently lift while the document claims a ground lock.
• Add measurable invariants for heel height, toe height, sole orientation, and foot drift during grounded ballet movements.

ROM acceptance criteria

• General movements retain conservative default behavior.
• A reviewed ballet configuration can represent the required turnout and ankle ranges without changing global defaults accidentally.
• Ground-contact failures are observable through diagnostics and tests.
• No documentation presents these limits as medical advice or individual capability guarantees.

Workstream 4: correct and validate the ballet examples

Treat the current ballet examples as experimental until reviewed by someone with relevant dance knowledge. Update source examples, generated movement pages, thumbnails/GIFs, prompt examples, and regression tests together.

Demi-plié

• Preserve first-position turnout throughout the descent and recovery.
• Keep both complete soles planted with no heel lift or lateral foot skating.
• Verify knees track consistently with the turned-out feet.
• Revisit the dorsiflexion requirement under the selected ballet/contact profile.

Elevé and Relevé

• Rename the current rise-without-plié example from "Relevé" to "Elevé."
• Start the Elevé example from first-position, not generic standing.
• Preserve turnout during the rise and controlled lowering.
• Add a distinct Relevé example that begins with a demi-plié before rising.
• Confirm terminology and movement with a dance-domain reviewer before marking either example ready.

Pirouette

• Start in first position and preserve hip external rotation throughout.
• For this example, turn toward the right gesture leg.
• Begin with a suitable third-position arm shape: right arm in front and left arm to the side.
• Bring the left arm in front during the turn while keeping the arms at a consistent height.
• Revisit plantarflexion for both ankles under the ballet profile.
• Represent spotting: focus remains forward until the head must turn, then returns to front quickly.
• Determine whether spotting can be authored as short existing phases or requires a dedicated gaze/focus/spot construct.
• Validate support-foot contact, turn direction, gesture-leg path, landing, and loop reset with automated invariants where possible.

Chassé

• Compare the current movement against an appropriate reference selected with a dance-domain reviewer.
• Correct the step-close-step mechanics, weight transfer, foot contact, turnout, timing, and travel path.
• Verify that root translation and foot constraints do not make the feet slide while the cues claim stepping.
• Record the reference and validation notes in the example so later edits do not regress the movement.

Example acceptance criteria

• Every published dance example has named reference material and review status.
• Cues describe only motion that is encoded and visibly rendered.
• Key contacts, paths, joint ranges, turn direction, and final orientation have deterministic tests.
• Updated public captures are generated only after the movement tests pass.

Workstream 5: make travel and rotation readable in the playground

• Add an optional, subtle floor reference that exposes orientation and distance without overwhelming the figure.
• Evaluate a grid, concentric stage markings, sparse metre markers, an origin marker, and a facing arrow.
• Consider a toggleable root path or foot-contact trail for travel and turn debugging.
• Show enough scale information to interpret the metre-based travel command.
• Test readability from front, side, three-quarter, and mobile camera views.
• Keep the default presentation suitable for non-technical viewers while providing a stronger debug mode for authors.

Acceptance criterion: a viewer can tell the initial facing, turn direction, approximate distance traveled, and return-to-origin behavior without reading the source.

Workstream 6: research Labanotation interoperability

Labanotation records movement through a notation system covering body part, direction, level, duration, and other movement information. A translator could provide established scores as test material for Posecode, but "straightforward" and "decent fidelity" are hypotheses to validate rather than assumptions.

• Document a mapping table from a bounded subset of Labanotation concepts to Posecode grammar and IR.
• Identify information Posecode currently cannot preserve, including weight transfer, support, direction/level nuance, path, dynamics, simultaneous events, focus, and whole-body spatial relationships.
• Select a small set of legally usable scores or purpose-built fixtures with increasing complexity: static position, grounded step, turn, and short phrase.
• Prototype a one-way Labanotation to Posecode conversion for the supported subset.
• Emit explicit diagnostics for lossy or unsupported constructs rather than fabricating plausible motion.
• Compare parsed phases, contacts, root path, joint landmarks, and rendered output against the source score.
• Require review by someone who reads Labanotation before making fidelity claims.
• Record whether Labanotation is best treated as an import format, a test oracle, or design research rather than a promised product feature.

Workstream 7: test the complex-teaching use case

Use the supplied 540 reference as a capability probe, not as an immediate promise that Posecode can reproduce it.

• Break the movement into required semantic events: preparation, support changes, takeoff, free flight, rotation, leg shapes, spotting/focus, landing, and recovery.
• Mark which events are expressible with the current grammar and which require new semantics.
• Pay particular attention to free flight, since the current authoring guide correctly treats it as unsupported.
• Determine the minimum language/runtime additions needed for a useful teaching visualization.
• Evaluate the claimed advantages: slow playback, scrubbing, alternate camera angles, and easy variants.
• Coordinate playback-speed work with Playground: Add UI buttons/slider for animation playback speed control #22.
• Do not add syntax solely for this example until it generalizes to other complex rotational or airborne movements.

Workstream 8: validate the audience and interface assumptions

The tester's audience observation is valuable but should be treated as a research hypothesis: many dance teachers and choreographers may prefer demonstrating with their bodies, may be uncomfortable with code, and may resist LLM-centered workflows.

• Make "LLM optional" clear in dance-facing material. The language, parser, validator, and renderer are the product foundation.
• Test direct editing, visual pose controls, movement-library composition, and import workflows before assuming prompt-first authoring.
• Use DanceForms as prior-art research for dance-oriented concepts such as poseable figures, movement libraries, sequence blending, stage playback, score views, and multi-angle inspection.
• Conduct a small number of asynchronous interviews or UAT sessions with dancers, teachers, choreographers, and movement notators.
• Ask which tasks are difficult today rather than asking whether they like AI-generated movement.
• Validate whether complex movement teaching, preserving movements an instructor cannot physically demonstrate, scrubbing, and showing variants are stronger entry points than general choreography authoring.
• Avoid presenting dancers and choreographers as a validated target audience until repeated evidence supports it.

Suggested priority order

P0: correctness and trust

• Make the spec discoverable
• Clarify contact semantics and cues
• Reproduce and diagnose the Demi-plié heel lift
• Correct naming/status for Elevé and Relevé
• Mark unreviewed ballet examples experimental

P1: representation and authoring

• Design ROM profiles or configurable limits
• Design custom start-pose overrides
• Correct Pirouette and Chassé with reviewer input
• Add floor/path orientation aids
• Investigate spotting semantics

P2: research and product direction

• Labanotation mapping prototype
• 540 capability probe
• Dance-oriented non-LLM authoring research
• Async domain-expert UAT

Non-goals for this umbrella issue

• Do not treat one tester's angle values as universal clinical truth.
• Do not weaken the general ROM defaults merely to make ballet examples render.
• Do not introduce male/female ROM presets as a substitute for individual configuration.
• Do not claim lossless Labanotation conversion before a notator validates it.
• Do not make LLM use mandatory for dance workflows.
• Do not attempt a full DanceForms replacement.
• Do not consider an example correct only because it parses without warnings.

Completion criteria for the umbrella

• Each workstream has either a completed implementation or a linked focused issue with an owner/status.
• Immediate documentation and mislabeled-example fixes are shipped.
• Ballet examples have an explicit review status and deterministic movement/contact checks.
• ROM/profile and custom-pose decisions are documented, even if implementation is deferred.
• Labanotation and 540 probes publish findings and unsupported semantics honestly.
• At least one follow-up UAT pass is completed asynchronously with a dance-domain reviewer.

References

• Posecode protocol specification
• Posecode LLM authoring guide
• DanceForms choreography software
• Dance Notation Bureau: Labanotation fundamentals
• Supplied 540 movement reference
• Playground: Add UI buttons/slider for animation playback speed control #22