# Trails Discriminate Union

> Use when reviewing public or queryable Trails outputs that expose union-like shapes to agents or surfaces. Helps decide whether stable discriminants are required and whether the issue is schema cleanup, advisory guidance, or Warden work.

- Skill: `outfitter-dev/trails-discriminate-union` (Agent Skill)
- Install (CLI): `npx skillmds@latest add outfitter-dev/trails-discriminate-union`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outfitter-dev/trails-discriminate-union/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: outfitter-dev (https://skillmd.com/u/outfitter-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/outfitter-dev/trails-discriminate-union

---


# Trails Discriminate Union

Use this skill when a trail output, derived view, query response, or public schema has multiple object-like branches that consumers must distinguish.

## Workflow

1. Confirm the shape is public or queryable. Focus on trail outputs, topo/query derived views, surface responses, or agent-consumed schemas.
2. Identify branch evidence: Zod schemas, JSON Schema derivation, tests, examples, and downstream surface behavior.
3. Look for a stable literal discriminant such as `kind`, `mode`, `type`, or another owner-approved field.
4. Check whether consumers currently branch by field guessing, optional-field presence, message text, or array position.
5. Recommend one of:
   - Add or preserve a stable discriminant in the owner schema.
   - Keep private/internal helper unions out of public doctrine.
   - Add advisory follow-up because schema metadata cannot prove the public shape yet.
   - Promote to Warden only with reliable fixtures and a narrow owner source.

## Authoritative Sources

- `packages/core/src/validation.ts`
- Surface builders that render output schemas.
- Tests that cover examples, MCP/HTTP schema rendering, or topo query output.

## Advisory Context

- PR #300 / TRL-564 context on queryable-contract hardening and public schema branch identity.
- Prior hardening audit theme: public or queryable object unions need owner-visible branch identity before Warden can enforce them.

## Must Not

- Do not demand discriminants for every private TypeScript union.
- Do not lint arbitrary `z.union(...)` without proving it reaches a public or queryable output.
- Do not break supported MCP/HTTP schema wrapping behavior to satisfy a generic rule.
- Do not infer branch identity from prose when a schema owner should expose it.

## Output

Return:

- Public/queryable status.
- Branch list and current discriminant evidence.
- Downstream consumer risk.
- Recommended owner schema change or advisory follow-up.
- Whether Warden can enforce the shape safely today.