# Principles Prompt Strategy

**Strategy name:** `principles`
**Prompt structure:** 7 sections in `system.md` + `examples.md`
**Approximate output:** 800-2,000 words in `system.md` (knowledge accessed via JSON tools; examples in `examples.md`)
**Philosophy:** Fewer rules, more examples. Trust the model's judgment for everything the examples already demonstrate.

---

## Use Case

A rules-light approach: instead of encoding every behavior as a rule, this strategy relies on real conversation examples to teach the model how to behave. Rules are minimal — only for things the model's common sense would genuinely get wrong.

> **Motion flavors.** `principles` is the single architecture; the sales *motion* is set by a thin overlay loaded alongside it — `principles-express`, `principles-consultative`, `principles-deep-nurture`, or `principles-book-the-call`. Each tunes Flow, Calibration, rapport technique, and target metrics. Pick the flavor by `(vertical, ticket_tier)` and how the creator closes.

Best for: any agent type (appointment-setting, community-building, low-ticket). Especially suited for agents with enough real conversation data to extract quality examples from.

---

## Design Philosophy

**The employee, not the contract.** A good employee learns from seeing great work, understanding the mission, and internalizing a few key principles — not from memorizing a 400-line compliance manual. This template follows the same approach:

1. **Examples do the heavy lifting.** Instead of writing "never repeat a link already sent" as a rule, show an example where the lead asks about the link again and the agent says "ya te lo pasé, lo pudiste ver?" The model generalizes from examples far more reliably than from rules.

2. **Principles, not micro-rules.** Instead of 15 hard rules, 5-7 principles that the model applies with judgment. Each principle passes the "common sense test": would a smart person with good judgment, seeing only the examples, get this wrong? If yes, it needs a principle. If no, the examples are enough.

3. **Guarded actions by default.** Every flow step that involves an action (send a link, ask a question, close the conversation) includes its own conditions inline. No separate rules section to cross-reference. (See PAT-004 in `knowledge/AGENTS.md`.)

4. **Voice from real messages, not from rules.** Instead of "max 25 words per message, no periods, voseo rioplatense," show 5-6 real messages from the creator. The model extracts tone, length, punctuation, and dialect from examples with near-perfect fidelity.

---

## Sections

### 1. Identity + Mission (~100 words)

**What it contains:**
- Who the agent is (creator's name, role, what they do)
- What the agent's job is (qualify leads, recommend products, answer questions — one clear mission)
- The conversion goal (book a call, sell a course, sign up for a community)

**How inputs are used:**
- `influencer_bio` + `creator_input` → synthesized into 2-3 sentences
- If input is sparse, keep it simple: "Sos [name]. [one-line description]. Tu objetivo: [goal]."

**What it does NOT contain:**
- Detailed credentials (move to Knowledge if needed)
- Long backstory
- Rule-like instructions disguised as identity

**Test:** Can you read this section in 10 seconds and understand who the agent is and what it does? If not, it's too long.

---

### 2. Voice (~200 words or 5-6 real messages)

**What it contains:**
- 5-6 **real messages** from the creator's actual DM conversations — the model will mirror this style
- Optionally: a 1-2 sentence voice summary ("casual, direct, uses voseo, minimal emojis")

**How inputs are used:**
- Extract from `instagram_conversation` data (real outbound messages from the creator)
- Prefer variety: one greeting, one discovery question, one link delivery, one objection handling, one close
- Preserve the creator's exact punctuation, emoji usage, capitalization, and message length

**What it does NOT contain:**
- Rules about formatting ("max 25 words", "no periods") — the examples teach this
- Banned phrases lists — if needed, add as a principle instead
- Tone descriptions that contradict the examples

**Why this works:** Models are exceptional at style matching from examples. 5-6 real messages teach punctuation, length, emoji usage, formality level, dialect, and warmth — all things that would take 10+ rules to specify.

---

### 3. Flow (max 8-10 linear steps)

**What it contains:**
- Numbered, ordered steps the conversation walks through (qualify → dolor → posicionar → cerrar → post-booking, etc.)
- Each step has an inline guard: "Si X → hacer Y" rather than separate condition+action
- Optional escape clauses (e.g., "Si llega por keyword → entregar recurso primero y después arrancar")
- Terminal-state rules: when to send NO_RESPONSE, when to close

**How inputs are used:**
- Derive from `creator_input` and the agent's use_case (appointment-setting → qualify+pitch+book; low-ticket → answer+upsell+close)
- Look at sibling agents in the same vertical for proven flow shapes

**Critical rule:** **The order is the behavior.** What appears first runs first. If keywords must take priority, they go before step 1. If a fast path exists ("if user already mentions duelo type, skip discovery"), state it inline at the relevant step.

**What it does NOT contain:**
- Branching trees or nested if-else logic — keep it linear; if an agent needs >10 steps or >2 levels of nesting, the flow is too complex (rewrite, not patch)
- Tool-call syntax in free text (e.g., `get_resource('booking')`) — the model copies that verbatim. Use prose ("envialo el link de agenda") and let examples show the actual call

---

### 4. Calibration (energy read + state-aware action)

**What it contains:**
- A short list of lead "energy states" the agent should distinguish (engaged / lukewarm / disengaged / emotional / hostile)
- For each state, the prescribed action — usually moves toward NO_RESPONSE faster as engagement drops
- A closing rule: when the agent has offered everything productive, the next response is NO_RESPONSE (don't loop)

**Why this section exists:**
Without it, agents over-extend conversations with disengaged leads, repeat themselves, or get drawn into emotional spirals. Calibration sits between Flow (mechanical step progression) and Principles (philosophical guidance) and tells the model how to read the room.

**Example shape:**
```
- Engaged (preguntas, contexto, interés claro) → avanzar normalmente
- Tibio (respuestas cortas, "puede ser") → una pregunta más; si no se mueve, NO_RESPONSE
- Desenganchado (no comparte info, evade) → NO_RESPONSE
- Emocional → una frase de empatía + propuesta + link; si sigue sin agendar, NO_RESPONSE
```

**What it does NOT contain:**
- Tone descriptions ("ser cálido") — Voice handles tone
- Re-statements of NO_RESPONSE triggers that the principles already cover

---

### 5. Principles (5-7 max)

**What it contains:**
- Only constraints that the model's common sense + examples would genuinely miss
- Each principle is one sentence, actionable, and self-contained

**The common sense test:** Before adding a principle, ask: "If a smart person saw only the Identity, Voice, Knowledge, and Examples sections, would they get this wrong?" If the answer is "probably not," the examples handle it — don't add a principle.

**Universal principles (include in every agent):**
These are safety boundaries that models can genuinely violate without explicit instruction:
1. **No visible reasoning** — the agent acts on its internal logic, never narrates it to the lead (one reply per turn, first-person, no pre-announcements, no echoing prompt tokens/thresholds). Use the ready paragraph in `agents/_TEMPLATE/sdk/system.md` (or `knowledge/reasoning-leak.md` §3 for English); if a deployed agent actually leaks, that doc has the diagnosis and fix.
2. **Never invent information** — only use facts from the Knowledge section or tools. No hallucinated URLs, emails, phone numbers, or product details.
3. **Never diagnose, prescribe, or promise specific results** — regardless of vertical. Redirect to the appropriate professional or resource.
4. **If someone appears to be a minor, disengage and refer to the team.**

**Common optional principles (add only if the examples don't cover it):**
- "No prices in chat — redirect to [call/page/team]" (for appointment-setting where pricing is sensitive)
- "Never send a resource without confirming interest first" (only if examples don't show this pattern)
- "After the lead says no, accept it — one warm close, then stop" (only if examples don't demonstrate graceful rejection handling)

**What it does NOT contain:**
- Formatting rules (examples teach formatting)
- Tone rules (Voice section teaches tone)
- Flow logic (Examples section teaches flow)
- Anything stated more than once

---

### 6. Tools (max 4, with explicit triggers)

**What it contains:**
- A short list of tools the agent can call (`lookup_keyword`, `get_resource`, `lookup_resources`, etc.)
- For each tool: when to call it ("antes de enviar cualquier URL de video" / "cuando el lead nombre un duelo específico"), and what to do with the result

**Critical rule:** Tools are called in prose, not in syntax. Write "consultar `lookup_resources` con el topic relevante" — never write the call literally as `lookup_resources({...})` in free text, because the model can leak that verbatim to the lead (PAT-006).

**What it does NOT contain:**
- More than ~4 tools (cognitive load + context cost)
- Tools that aren't actually wired up in `v5Config` (verify before listing)

---

### 7. NO_RESPONSE (3 lines: when, how, what)

**What it contains:**
- **When:** the trigger conditions (post-booking + materials sent, descalificado, off-topic insistencia, emojis solos, abuso, "gracias" sin acción)
- **How:** literal — the response is the word `NO_RESPONSE` alone, no other text
- **What:** confirms it ends the turn (platform routes the silence)

**Why isolated:** NO_RESPONSE is the only stop token the platform processes (AGENTS.md §1.8). PARAR / STOP / "no continuar" don't work. This section is mandatory in every agent.

**What it does NOT contain:**
- Long lists of every conceivable scenario — keep it tight; principles can carry the rest
- A separate "closure_message" — that re-engages the lead, defeating the purpose

---

### Examples (lives in `examples.md`, not in `system.md`)

**What it contains:**
- 10-15 real or curated conversations that demonstrate the complete range of agent behavior
- Each example is a full conversation (not just a snippet), showing the agent from greeting to close

**Coverage checklist — examples should collectively cover:**

| Scenario | What it teaches the model |
|----------|--------------------------|
| Happy path (lead qualifies, converts) | The complete flow from greeting to conversion |
| Resource/link delivery | When and how to send links (and what to do when already sent) |
| Objection handling | How to respond to price concerns, skepticism, "I'll think about it" |
| Disqualification / graceful close | How to exit when the lead doesn't fit |
| Emotional/sensitive lead | How to adapt tone to someone in distress or excitement |
| Re-engagement (lead returns after silence) | How to resume without re-sending links or restarting |
| Off-topic question | How to redirect without being dismissive |
| Keyword trigger (if applicable) | How to deliver the resource and resume flow |
| Price objection (if the program has a price) | How to handle the price concern without giving the price in chat (or with, depending on the agent) |

**How inputs are used:**
- Source from real conversations (pull them with the `get_conversations` MCP tool)
- Curate for quality: pick conversations where the creator (or a well-performing version of the agent) handled the situation well
- If real conversations are insufficient, hand-author representative examples based on the creator's voice + the knowledge base

**Formatting:**
```
### Example N: [scenario label]

**User:** [message]
**Agent:** [message]
**User:** [message]
**Agent:** [message]
...
```

**Critical: examples must be self-consistent.** Every example must follow the principles. If a principle says "no prices in chat" but an example shows a price, the model will follow the example. (This is PAT-001 from `knowledge/AGENTS.md`.)

---

## Safety Boundaries (embedded, not separate)

Safety rules are embedded in the Principles section (items 1-3 above), not in a separate block. This follows the Guarded Actions principle (PAT-004): constraints are enforced at the point of action, not in a distant rules section.

If the agent's vertical requires additional safety boundaries (e.g., wellness: "never interpret lab results", finance: "never give specific investment advice"), add them as principles — but keep the total under 7.

---

## SDK Mapping

When splitting a principles-template agent into SDK:

| Section | SDK file | Cached? |
|---------|----------|---------|
| Identity | `system.md` (top) | Yes |
| Voice | `system.md` (inline) or `examples.md` (voice samples) | Yes |
| Flow | `system.md` (inline) | Yes |
| Calibration | `system.md` (inline) | Yes |
| Principles | `system.md` (inline) | Yes |
| Tools | `system.md` (inline) | Yes |
| NO_RESPONSE | `system.md` (inline) | Yes |
| Knowledge (data) | `program.json`, `resources.json`, `keywords.json`, `objections.md`, `knowledge_base.md`, `case_studies.json`, `personal_story.md` | Tools (on-demand) |
| Examples | `examples.md` | Yes |

**Target:** `system.md` should be under 2,000-3,500 tokens. Knowledge data is *not* in `system.md` — it lives in JSON / markdown tool files and is accessed on-demand. Examples are cached separately.

---

## Example Rotation Model

Examples are the **living part** of the prompt. Principles are static. Knowledge is reference. But examples grow and rotate as you learn what the agent gets wrong.

**Rules:**

1. **Cap at 15 examples.** If you need to add example #16, retire the oldest example that covers a scenario the agent has been handling flawlessly for 2+ weeks.
2. **Every customer complaint = a new example.** When a customer screenshots a bad interaction, the correct version of that exact conversation becomes a new example. Don't add a rule — add an example.
3. **Every iteration should ask: "Is this fix an example or a principle?"** Default to example. Only add a principle if the fix cannot be demonstrated through a conversation.
4. **Freshness check (when iterating, via `cortex-iterate` / `cortex-analyze`):** For each example, check if the scenario it covers has appeared in recent conversations. If the agent handles it correctly in 10+ real conversations → the example earned its place. If the scenario never appears → candidate for retirement when space is needed.
5. **Rotation log:** When retiring an example, note it in `changelog.md`: "Retired Example N (scenario: X) — agent handles correctly in production. Replaced with Example M (scenario: Y) from customer complaint on YYYY-MM-DD."

**Why rotation matters:** A static set of 10 examples teaches the agent to handle 10 scenarios. A rotating set teaches the agent to handle every scenario that has ever gone wrong — and the examples that remain are the ones the model actually needs.

---

## Cross-Agent Learning

This template does NOT reference `playbook.md` (deprecated). Cross-agent learnings come from:

1. **`knowledge/AGENTS.md`** — Validated patterns (PAT-xxx) checked during creation and iteration
2. **Sibling agent scan** — During `cortex-create` and `cortex-iterate`, scan changelogs from agents with the same use-case or vertical for applicable learnings
3. **Examples from high-performing siblings** — When an agent lacks good real conversations, borrow example patterns (not verbatim) from agents in the same category

---

## Template Compliance Criteria (for `cortex-analyze` review)

| Check | Pass condition |
|-------|---------------|
| Identity | Present, under 100 words, clear goal |
| Voice | 5+ real message samples OR 1-2 sentence summary + 3 samples |
| Flow | Present in `system.md`, ≤10 linear steps, every action has an inline guard |
| Calibration | Present in `system.md`, names ≥3 energy states with prescribed actions |
| Principles | 5-7 principles, each one sentence, passes common sense test |
| Tools | ≤4 tools, each with explicit trigger; no tool-call syntax in free text |
| NO_RESPONSE | Mandatory section; literal `NO_RESPONSE` token, no closure_message |
| Knowledge data | All URLs valid, no placeholders, lives in JSON/markdown tool files (not `system.md`) |
| Examples | 10-15 conversations in `examples.md`, coverage checklist met, consistent with principles + flow |
| No rule bloat | `system.md` under 3,500 tokens (excluding knowledge data) |
| Example coverage | All 7 base scenarios + applicable conditional scenarios (keyword trigger, price objection) covered |
| Example freshness | Examples address recent failure patterns, not only original creation scenarios |
| PAT-004 compliance | No unguarded actions in flow or examples |
| PAT-001 compliance | Examples consistent with principles + flow (no contradictions) |