Semantic Layer

Model-neutral routing across trial design skills

Define and normalize shared clinical trial design vocabulary for gsDesign ecosystem skills. Use when Codex needs consistent meanings for endpoint family, estimand, hypothesis type, information, timing, boundaries, multiplicity, adaptation, simulation, or other semantic fields before choosing a package workflow.

Purpose

The semantic layer maps natural-language clinical trial design requests to normalized trial-design intent and then to package-specific workflows.

It is intentionally lightweight:

  • shared vocabulary in glossary/
  • package crosswalks in crosswalks/
  • router and glossary skills in .agents/skills/
  • routing examples in evals/

Router Skill

Trial Design Semantic Router

Use this skill before package-specific skills when user intent needs to be translated into a trial-design workflow.

Resources

  • Routing rules: references/routing-patterns.md
  • Shared vocabulary: ../../../glossary/core-concepts.md
  • Package crosswalks: ../../../crosswalks/*.yaml
  • Routing examples: ../../../evals/natural-language-requests.yaml

Workflow

  1. Normalize the request into semantic fields: endpoint family, estimand, hypothesis type, design family, timing basis, information source, boundaries, multiplicity, adaptation, and simulation.
  2. Read the relevant glossary entries and package crosswalks only as needed.
  3. Select the smallest set of package skills that can satisfy the intent.
  4. Identify missing inputs that change the workflow, analysis, or package choice. Ask only for those inputs before implementation.
  5. Hand off to the selected package skill for code patterns and API details.
  6. Explain the routing decision in terms of user intent and package capability.

Output Pattern

When useful, summarize routing with this compact structure:

intent:
  endpoint_family:
  estimand:
  design_family:
  timing_basis:
  information_source:
  multiplicity:
  adaptation:
  simulation:
routing:
  skills:
  packages:
  workflow:
  missing_inputs:

Keep the structure short. Do not force every field when the user asked a narrow question.

Clarification Rule

Ask a clarification question only when the answer changes the recommended package, workflow, statistical method, or required inputs. Otherwise, make a reasonable assumption and state it.

Glossary Skill

Trial Design Glossary

Use this skill to standardize terminology before routing or implementation.

Resources

  • Canonical glossary: ../../../glossary/core-concepts.md
  • Usage notes: references/using-glossary.md

Workflow

  1. Map user terms to the closest canonical concept.
  2. Preserve clinically meaningful details such as endpoint family, estimand, time scale, population, and intercurrent-event handling.
  3. Flag terms that are ambiguous enough to change the package or workflow.
  4. Hand off to semantic-router when package selection is needed.

Do not perform package-specific calculations from this skill. Use the package skill selected by the router.

Current Crosswalks

  • crosswalks/gsDesignNB.yaml

Current Evaluation Examples

  • evals/natural-language-requests.yaml