Kinds

A kind is the type of question being asked. It does two things: it routes proposals back to the consumers that handles_kinds it, and it determines the JSON Schema the expert’s free-text reply is structured into. The canonical schemas live in spec/schemas/kinds/*.json in the repository.

Built-in kinds

glossary.definition

For defining a term. Structured shape:

Show schema

definition

string

required

caveats

array

required

Edge cases or qualifications on the definition.

examples

array

Optional illustrative examples.

{
  "definition": "A paying account with activity in the last 90 days",
  "caveats": ["Excludes trial accounts", "Q2 reporting uses calendar quarters"],
  "examples": ["An account that logged in and has an active subscription"]
}

freeform.answer

For any other question. Structured shape:

Show schema

summary

string

required

A concise answer.

details

string

Optional supporting detail.

{
  "summary": "Paying accounts active in the last 90 days",
  "details": "Finance treats a login or a billable event as activity."
}

Structuring behavior

When an expert replies, ShoulderTap (with an LLM configured) extracts the structured form and a confidence score. The raw answer is always preserved. If extraction fails or confidence is below 0.3, structured is null but answer still holds the expert’s exact words — a consumer should always be prepared to fall back to answer. Without an LLM configured, structured is always null and the raw reply passes through verbatim.

Custom kinds

A consumer can register its own kind with a custom JSON Schema at registration time, via the kind_schemas field on ConsumerRegistration. A custom schema for a kind takes precedence over a built-in of the same name, so you can also override how a built-in kind is captured for your consumer.

Overview

Contracts

Endpoints

Built-in kinds

Structuring behavior

Custom kinds

​Built-in kinds

​Structuring behavior

​Custom kinds

Built-in kinds

Structuring behavior

Custom kinds