outfitter-dev 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
- Confirm the shape is public or queryable. Focus on trail outputs, topo/query derived views, surface responses, or agent-consumed schemas.
- Identify branch evidence: Zod schemas, JSON Schema derivation, tests, examples, and downstream surface behavior.
- Look for a stable literal discriminant such as
kind,mode,type, or another owner-approved field. - Check whether consumers currently branch by field guessing, optional-field presence, message text, or array position.
- 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.