Relational Prompt Language (RPL)

RPL is a Markdown-embedded reasoning framework with associated logic for structuring how an LLM reasons about user requests in an abstract, inspectable way. Instead of relying only on highly tuned prose and then guessing what the model inferred, you can declare explicit relations, goals, and constraints so reasoning state is easier to inspect, question, and improve.

Document map

Document	Role
motivation.md	Problem framing and language overview (why RPL, how to read it)
scope.md	Boundaries, `?` vs `$`, use cases, document index
theory.md	Bloom, CALM, monotonicity, formal vs agent layer
vision.md	Central ideas, trace, lazy extension summary, design principles
cognition.md	Latent biasing, trace as ground, stratified reasoning, prose-first materialisation
bootstrapping.md	Pedagogical bootstrap for a reasoned agent (tables, canonical forms, intent)
agent-mck.md	RPL as metacognitive kernel: intent tracking, context stack, invariants
specification/rpl.md	Normative base spec: syntax, semantics, runtime, grammar
specification/lrpl.md	Normative LRPL delta (lazy expressions, memos, stdlib)
specification/logics.md	Additional logics: existential, modal, interpretive (`<@`, `@>`)
tutorial/	Continuations of the worked example (full recipe protocol, cook mode, kitchen context, scheduling, handoff)

The sections below walk through one worked example: a single-chat recipe-building and cooking prompt that starts as ordinary Markdown, gets misread in predictable ways, then becomes more reliable as you layer in relational structure. Bootstrapping is turning RPL on in system or project instructions so Markdown in scope materialises as RPL; relation heads on the task prompt appear only where a named fact addresses a concrete failure mode. Relation names stay concrete (who/when/what) rather than vague validators—see content/rpl/rpl.md on arity and subject–value facts. They are not a substitute for the specifications.

Start From A Plain Prompt

Start with a complete prompt for a real task, not an isolated line item.

Here is a plausible system prompt for helping a home cook plan and execute a meal in one conversation: explore options, refine for their kitchen, lock ingredients, publish a readable recipe card, then optionally enter stepwise cook mode.

# Collaborative Recipe Session

You are helping a home cook plan and execute a meal in this single chat. The
cook may need clear steps, small chunks of information, and explicit checkpoints
rather than long unstructured paragraphs.

## Explore Before Committing

Before you commit them to a dish or a final ingredient list, be explicit about
which stage of this workflow you are using.

Offer a small set of candidate dishes that fit what they have said so far (time,
effort, diet, vibe). Do not behave as if a recipe is chosen until they pick one.

## Refine With Equipment And Process

Ask what equipment and techniques they are willing to use. Adjust the leading
candidates; drop ones that clash with their kitchen or patience level.

## Lock Ingredients Before The Recipe Card

Agree the ingredient list with approximate quantities before you write the full
recipe. Flag substitutions only after they confirm the list.

## Recipe Card Overview

Produce a classical recipe shape: yield, ingredients, numbered steps with times
and sensory cues where it helps. Warn before steps that are easy to get wrong
or hard to undo.

## Cook Mode Only When They Ask

When they explicitly enter cook mode, go one step at a time. Passive reminders
(oven preheating while something rests) are fine; do not start two hands-on steps
at once. If they interrupt with a question, answer in the context of the
**current** step without restarting the whole plan.

## Scheduling

If they give a target serve time or pacing constraint, respect it. Work backward
for long waits, marinades, or multi-stage prep.

## Tone

Be neutral, precise, and instructional. Avoid dumping everything at once.
Group related tasks. Prefer a short warning over silently “fixing” a risky move.

This is already a meaningful process. It names workflow stages, requires turn-taking, and commits to specific output shapes (candidates, locked ingredients, numbered steps).

How The Model Can Misread It

A model can still abuse or misread that prompt in ways that show up in real cooks’ chats:

It may jump to a full recipe during “explore” and tacitly treat a candidate as chosen—recipe identity drifts from what the user thinks is locked in.
It may collapse several candidates into one “best” dish without a clear selection event.
It may skip or compress ingredient lockdown and “helpfully” rewrite the list while drafting steps.
In cook mode it may ignore the numbered-step format, paste the whole recipe again, or lose track of the current step while answering a sidebar question.
It may forget pantry, equipment, or serve-time constraints unless the user repeats them—there is no stable kitchen context or schedule anchor in the reasoning surface.
If the user switches to a fresh chat later, it may lose where this session sits inside a longer feast prep—handoff context vanishes.

This is where RPL starts to help. It does not replace the prose. It gives the model an inspectable reading of what the prose is already trying to say—phases, commitments, collections, and outputs—using relations that sound like rows you could put in tables: a step has an ordinal and text, a session targets a serve time, a recipe locks ingredient lines.

Bootstrap RPL

Bootstrapping means turning RPL on in system or project instructions. That is enough for the agent to treat Markdown in scope as the RPL surface: structure and prose materialise into relations as they are encountered (see motivation.md on prose-first authoring). Shell turns, signatures on headings, and fenced rpl blocks then behave as specified without an extra “how to read this” layer. For normative detail and examples such as RPL shell mode and $json, see content/rpl/rpl.md.

Add Relation Heads For Specific Failures

Introduce a signature on a heading—or a small fenced rpl block—when the prose alone keeps misfiring on something you can name. Skip headings that are already stable; empty ceremony makes the surface noisier without improving behavior.

Example: phase drift

If the model jumps phases or loses track of which stage applies, anchor workflow phase first. Leave “Explore”, “Refine”, and the rest as ordinary headings until you need more structure there.

# Collaborative Recipe Session - %recipe-session(?phase) <- recipe-session(?phase)

You are helping a home cook plan and execute a meal in this single chat.
…

## Where we are - current-workflow-phase($phase)

Before actions that commit the user (locking ingredients, writing the recipe
card, advancing cook-mode steps), state which workflow phase applies.

```rpl
names-workflow-phase("explore")
names-workflow-phase("refine")
names-workflow-phase("lock")
names-workflow-phase("overview")
names-workflow-phase("cook")

current-workflow-phase($phase)
recipe-session(?phase) <- current-workflow-phase(?phase)
```

Closed phase labels plus an explicit current phase give the model a single place to look before it acts—without yet turning every section into a relation.

Example: ingredient list drift

If the model skips lock-in or silently rewrites quantities while drafting steps, attach a collection-shaped head only on the ingredient-lock section when that failure shows up in traces.

## Lock Ingredients Before The Recipe Card - locked-ingredient-line($ingredient, $qtyNote)

Agree the ingredient list with approximate quantities before you write the full
recipe. Flag substitutions only after they confirm the list.

```rpl
ingredient-lines([& ?i ?q]) <- locked-ingredient-line(?i, ?q)
```

locked-ingredient-line($ingredient, $qtyNote) is a binary-shaped record per line; the rule lifts many rows into one ingredient-lines value when you need “the whole list” in later queries or summaries.

Keep extending the same document the same way: more signatures and rules only where behavior still slips. $ marks values the model must collect or that arrive from outside the current deduction; ? marks values already known or derivable—see scope.md and the base spec.

Continue In The Tutorials

Start with tutorial/00-recipe-protocol.md for the rest of the same recipe document: full signatures, collections, meal-prep-brief, recipe-artifact, branch goals %recipe-session-planning / %recipe-session-cook, the assembled protocol block, shell queries, and trace hooks. After that, each tutorial adds one capability.

Tutorial	Capability
tutorial/00-recipe-protocol.md	Tighten and complete the recipe protocol in one place
tutorial/01-cook-mode.md	Current step, questions without losing recipe identity
tutorial/02-kitchen-context.md	Pantry/equipment context via `$index(...)`
tutorial/03-scheduling.md	Serve-time targets and stage-shaped prep
tutorial/04-handoff.md	Trace parking and continuation in a new session

LRPL builtins such as $json, $write, and $index are specified in specification/lrpl.md. Optional interpretive and modal operators are in specification/logics.md.

Where It Lives

An RPL workflow document is ordinary Markdown. Where you put it determines when and how it runs. All three patterns below use exactly the same RPL; what varies is scope and triggering.

In a single prompt — paste the protocol into a conversation when you need structured intake for a one-off task. With RPL enabled for the session, the same Markdown is read relationally without extra preamble. Useful for ad-hoc workflows mid-conversation.

In a project system prompt — place it in your project’s rules or instructions file. Every conversation in that project inherits the protocol. Useful for recurring workflows: code reviews, onboarding, standing recipe assistants.

As an agent skill — wrap the protocol in a skill manifest (YAML frontmatter with name and description) and package it as a SKILL.md. Skill-aware clients (Cursor, Claude Code) load it on demand when a user’s request matches the description. The protocol is portable because it is just Markdown with structure.

For multi-phase handoff — keep each execution bounded to one chat session, then embed selected trace facts in issue comments or third-party systems for the next session. Example: park recipe-artifact slices and current-recipe-step bindings so a later session does not hallucinate a new menu.

For enterprise boundary guidance, see enterprise.md.

What RPL Does Not Do

RPL is a protocol language, not a programming language:

No imperative control flow. No loops, conditionals, or mutable state. Branching comes from goal disjunction; iteration from set semantics.
No computation. RPL declares what must hold. The agent and its tools do the work.
No enforcement. RPL is a contract between author and agent, interpreted in good faith. Constraints and traces provide accountability, not a sandbox.
Agent judgment fills gaps. Where the spec is silent, the agent decides. This is deliberate — RPL structures the protocol, not every micro-decision.
Not an enterprise runtime substrate. Do not treat RPL as infrastructure for long-running mission-critical application control loops.

RPL language