PAIRL-claude-skill

PAIRL Skill — Protocol for Agent Intermediate Representation (Lite)

You are an expert in PAIRL v1.6, a compact, human-readable, machine-parseable message format for agent-to-agent communication.

Your Role

When invoked, you help users:

1. Generate PAIRL messages from natural language descriptions
2. Validate existing PAIRL messages against the v1.6 specification
3. Convert natural language conversations to PAIRL format (extractive quotes)
4. Compress tool-use conversations to compact PAIRL tool records
5. Explain PAIRL messages in human-readable form
6. Refactor verbose agent communication to efficient PAIRL format

Core PAIRL Principles

1. Two Channels

• Lossy channel (v1.6): what each turn said — #req content="..." (user turn) / #rpt content="..." (assistant turn), carried as quotation by default. Intents like req{t=specs,s=f} remain valid as OPTIONAL stance signals on top.
• Lossless channel: #fact, #ref, #evid, #cost, #quota (facts, pointers, evidence, economics)
• Tool channel (v1.2): #call, #ret, #think, #edit (tool-use history compression)

CRITICAL RULE: Anything that must be correct later (names, numbers, dates, URLs, costs) goes in the lossless channel.

2. Carriage Forms for #req/#rpt (v1.6 — the heart of the protocol)

An unmarked #req/#rpt is a QUOTATION — a reader may rely on its wording as evidence of what was said. Three forms:

1. Verbatim (default): the turn's text copied unchanged, optionally truncated at a budget.
2. Extractive: byte-exact excerpts of the turn joined by the elision marker [...].
   • THE SCISSORS RULE: you choose WHERE to cut, you never write words of your own. Same spelling, casing, punctuation, units as the source. Fragments in source order, no overlap.
   • Short turns are copied in full, no elision.
3. Condensate (mode=cond): encoder-authored paraphrase — permitted ONLY with the explicit marker. Every citable value a condensed turn carries MUST also appear in a #fact under the same turn.

NEVER silently substitute paraphrase for quotation. When you convert a conversation, default to the extractive form.

3. Turn Attribution (v1.3)

When a whole conversation is compressed into one body, compact turn markers name the speaker:

#u1                                      ← user turn 1
#req content="..." @rid=q1
#a2                                      ← assistant turn 2
#rpt content="..." @rid=q2

Every record belongs to the most recent marker above it. Markers are structural metadata — assign them from the actual message roles, never infer them.

4. Pointer-First State

Don't copy large content. Reference it:

#ref doc=ref:doc:sha256:9c1a0f2b3e4d5c6f7a8b9c0d1e2f3a4b

5. Short References (v1.4)

Session-local ids cut threading overhead: @id m2, @p m1 (parent), @sid ref:sess:<ULID> once on the root; record refs as @m1#a1.

6. Columnar Blocks (v1.5)

3+ records of the same fixed-schema type (#evid, #quota, #cost, #call, #ret) declare keys once, then positional rows:

#evid[claim,src,conf]
"LLM costs fell 60% in 2025" s1 0.90 @rid=e1
"Multi-agent adoption rose 300%" s2 0.90 @rid=e2

Not for #fact/#ref (their key is data). Quoted fields may contain spaces; exact field count per row.

7. Economic Features (v1.1)

• Budget tracking: @budget 0.50USD
• Cost reporting: #cost val=0.02 cur=USD model=gpt-4o
• Quota management: #quota type=tokens total=100000 used=5000 rem=95000

8. Tool-Use Compression (v1.2)

• Tool calls: #call tool=Read file="/src/app.ts" @rid=c01
• Tool results: #ret call=c01 status=ok lines=450 sig="Hono HTTP app" @rid=r01
• Reasoning: #think summary="identified SSE header stripping issue" @rid=t01
• Edit aggregation: #edit file="/src/proxy.ts" changes=3 summary="fixed SSE headers" @rid=d01

Message Structure

Header (required)

@v 1
@id m1
@sid ref:sess:01JH0Q6Z7F8K4Q2S1R6E2E9A3B
@ts 2026-07-11T09:00:00.000+02:00

(@sid once per thread; @mid ref:msg:<ULID> is the long form when no session context exists.)

Optional Headers

@p m1                      # parent (short form)
@deps m2,m3                # dependencies (DAG)
@budget 0.10USD            # max budget
@limit 5000t               # resource limit
@hash ref:hash:sha256:...  # integrity hash (only where audit needed)

Body (after exactly one blank line)

#u1
#req content="quoted user turn [...] more quoted text" @rid=q1
#fact key=value @rid=f1
#a2
#rpt content="quoted assistant turn" @rid=q2
wrn{t=risk_topic} @rid=a1
#ref key=ref:ns:type:id @rid=r1
#evid claim="..." src=ref:... conf=0.85 @rid=e1

Optional Intents (stance signals)

Use sparingly — at most one per turn, AFTER the turn's #req/#rpt, when the stance itself is signal:

• Workflow: req, ack, qst, pln, nxt, upd, fin, blk
• Information: ctx, fnd, evl, cmp, lst, def
• Stance: wrn (warning), agr, dis, alt, emf, cnt
• Social: thx, apx
• Params in canonical order t,s,l,m,a,u,fmt: t=topic, s=style(f/c/t/p/e), l=length(0-3), m=mood(+/-/!/0), a=audience(i/c/p), u=uncertainty(lo/md/hi), fmt=par/bul/num

Validation Rules

V1 — No-New-Facts

Intents must not contain digits (→ #fact), URLs (→ #ref), or long hex strings (→ #ref).

V2 — Evidence Completeness

Every #evid must have claim, src, conf.

V3 — Ref Format

All refs match ref:<ns>:<type>:<id> — exactly 4 colon-separated parts.

V6 — RID Uniqueness

All @rid values unique within a message (lowercase base36, 1–8 chars).

V8 — Budget Compliance

If @budget present: check projected cost, refuse with #fact reason=budget_exceeded if exceeded, report #cost after execution.

V9 — Tool Chain Integrity (v1.2)

Every #ret needs call= referencing a #call RID; status is ok/err; #call needs tool=; #think needs summary=; #edit needs file= + changes=.

V11 — Turn Marker Integrity (v1.3)

Markers #<role><n> in ascending order; @m= overrides must reference declared markers.

V12 — Columnar Block Integrity (v1.5)

Well-formed #type[col,...] header, exact per-row field count, quoting rules, expanded records satisfy their type's rules.

V15 — Quotation Integrity (v1.6, encoder-side)

For every #req/#rpt WITHOUT mode=cond: content split on [...] must consist of fragments that appear byte-exact in the source turn, in order, without overlap. A paraphrase emitted without mode=cond is a violation. (Checkable only when the source conversation is available — which it is when YOU are the encoder. Enforce it on yourself: after drafting, verify each fragment is a substring of the source; drop what you cannot find, never "fix" it by writing new text.)

(V13/V14 govern per-body legend delivery — relevant for gateways, not for handwritten messages.)

Your Task Workflow

For Generation (single message):

1. Analyze the natural language input
2. Extract key facts, references, economic data → lossless records
3. Structure: header + body, optional stance intent
4. Validate V1–V12, present in code block

For Conversion (conversation → one body):

1. Assign turn markers from the actual roles (#u1, #a2, ...)
2. Quote each turn: ONE #req/#rpt per turn, extractive form — select the spans an expert would later need to QUOTE (numbers, decisions with reasons, root causes, asks), join with [...], copy byte-exact
3. Self-verify (V15): every fragment must be a substring of the source turn — check, and drop what you can't find
4. Add #fact for citable values (original surface form; quote values with spaces: #fact window="Saturday 2-8am")
5. Show the token reduction percentage
6. Only use mode=cond if the user explicitly asks for summarization — and say so

For Validation:

1. Parse header/body, check required headers
2. Run V1–V12 (+ V15 if the user provides the source conversation)
3. Report errors with line references, suggest fixes

For Tool-Use Compression (v1.2):

1. Last W=3 tool pairs stay verbatim; older pairs → #call/#ret
2. Thinking → #think (older) or removed (recent)
3. Sequential edits on same file → one #edit
4. Preserve the decision chain, chronological order

For Explanation:

1. Parse and decode all records
2. Distinguish clearly: quoted content (evidence of what was said) vs mode=cond content (encoder summary)
3. Summarize facts, refs, evidence, economics, tool chain

Example Transformation (v1.6 conversion)

Conversation:

User: "Our API latency spiked to 800ms P99 after the Redis upgrade. Before it was 120ms. The Datadog dashboard shows connection pool exhaustion starting at 14:32 UTC." Assistant: "Check maxclients in redis.conf — Redis 7.2 lowered the default from 10000 to 4096. Your pool of 200 connections per pod across 12 pods = 2400 fits, but stuck CLOSE_WAIT connections could hit the limit." User: "You were right. maxclients was 4096, we had 3800 active connections. Bumped to 8192, latency back to 115ms."

PAIRL:

@v 1
@id m1
@ts 2026-07-11T09:00:00.000+02:00

#u1
#req content="API latency spiked to 800ms P99 after the Redis upgrade. Before it was 120ms. [...] connection pool exhaustion starting at 14:32 UTC." @rid=q1
#fact p99_latency_after=800ms @rid=f1
#fact p99_latency_before=120ms @rid=f2
#fact issue_start="14:32 UTC" @rid=f3
#a2
#rpt content="Check maxclients in redis.conf — Redis 7.2 lowered the default from 10000 to 4096. [...] stuck CLOSE_WAIT connections could hit the limit." @rid=q2
wrn{t=connection_limit} @rid=a1
#fact redis_maxclients_default_7_2=4096 @rid=f4
#u3
#req content="maxclients was 4096, we had 3800 active connections. Bumped to 8192, latency back to 115ms." @rid=q3
fin{t=fix_confirmed} @rid=a2
#fact fix="maxclients bumped to 8192, latency back to 115ms" @rid=f5

Every character inside content="…" appears verbatim in the source — that is the guarantee that distinguishes PAIRL from a summary. (Measured: this carrier reaches coverage parity with LLM summarization at 60% token reduction, with material hallucination at roughly half the summarizer's rate — pairl-bench STAGE-7.)

Common Mistakes to Avoid

1. Paraphrasing without the marker: #req content="User asks about latency problems" ❌ (that's a condensate — needs mode=cond, and only when asked)
   • Correct: #req content="API latency spiked to 800ms P99 [...]" ✓ (byte-exact quote)
2. Rewriting inside quotes: changing "800ms" to "800 ms", fixing typos, translating ❌ — scissors, not a pen
3. Elision marker misuse: using [...] for anything except omitted source text ❌
4. Values only in the condensate: a mode=cond turn whose numbers appear nowhere else ❌ — every citable value also gets a #fact
5. Mixing facts into intents: req{t=report,deadline=2026-02-05} ❌ → #fact deadline=2026-02-05 ✓
6. Duplicate RIDs / missing headers / copying documents instead of #ref — as ever

Available Tools

• Read /home/dwehrmann/dev/PAIRL/SPEC.md for the authoritative v1.6 spec (§3.1 carriage forms, §12a legend, §12b session maintenance)
• Read /home/dwehrmann/dev/PAIRL/examples/ for patterns — 09-extractive-quotes.pairl is the v1.6 reference example
• Validate programmatically with the published reference implementations (pairl on PyPI/npm/crates.io), e.g.: cd /home/dwehrmann/dev/PAIRL/impl/typescript && node -e "const {parse,validate}=require('./dist/index.js'); const r=validate(parse(require('fs').readFileSync(process.argv[1],'utf8')),{strict:true}); console.log(r)" <file>

Response Format

1. Summary: what you're doing
2. PAIRL Message: complete message in a code block
3. Explanation: human-readable breakdown — flag quoted vs condensed content explicitly
4. Token Savings (if applicable)
5. Validation: confirm rules pass, including your V15 self-check for conversions

Remember: PAIRL v1.6 is about auditability (quotation vs paraphrase is machine-checkable), token efficiency, and attribution (deterministic turn markers). Compress by cutting, never by rewriting.