Skip to content

Prompt Design

This page documents the prompt engineering approach, lessons, and controls used for LLM agents in BDPD. Content is drawn from the preliminary LLM case studies (DeepSeek v4-flash, single-model, fixed seed) documented in the paper appendix.

Source of truth: the code

This page paraphrases the prompts for explanation. The authoritative, verbatim prompt text lives in the agent code and is what actually runs. When the two disagree, the code wins. To read or change the exact wording:

What Where (canonical)
Commons-game system prompt (rules, response format) agents/bdpd_agent.py — BASE_GAME_RULES, JSON_RESPONSE_INSTRUCTION / JSON_RESPONSE_INSTRUCTION_NO_TALK / BARE_NUMBER_INSTRUCTION, assembled by get_system_prompt()
Archetype persona nudges agents/bdpd_agent.py — ARCHETYPE_NUDGES (aggressive, conservative, adaptive, random)
Per-turn user prompt (observation -> text, inbox, pacts) agents/bdpd_agent.py — obs_to_text()
Cheap-talk / governance tool descriptions the model reads agents/bdpd_tools.py — make_action_tools() (broadcast, send_private, announce_intended_harvest, propose_pact, accept_pact, pledge)
Card-game system + turn prompts agents/cards_ai_play.py — build_system_prompt() and the per-turn template

Every LLM call is also logged verbatim by the TraceWriter (system-prompt hash, full user message, tool calls) — see Agent SDK. So the exact prompt for any recorded run is recoverable from its trace, independent of this page.

Prompt Structure

LLM agents receive a system prompt defining the game rules, their archetype, and behavioural constraints, followed by a turn prompt with the current game state and history.

System Prompt

The system prompt includes:

  1. Game rules summary — Turn structure, Forest Die mechanics, victory conditions, core concepts
  2. Archetype description — The agent's role, strategic profile, and card effects
  3. Current hand — Cards available to play this turn
  4. Behavioural nudge (optional, --nudge) — Archetype-specific strategic guidance
  5. Hard constraint (optional) — Non-negotiable rule (e.g. Collapse Brake)

Turn Prompt

Each turn, the agent receives:

  • Current Forest Health
  • Forest Deck estimate (with optional --forest-noise Gaussian noise)
  • Opponent actions from the previous turn
  • Agent's Stockpile, Capacity, Patience tokens
  • Hand contents
  • Turn number and defection status (Stranger-King)

Behavioural Controls

Archetype Nudges (--nudge)

Soft guidance injected into the system prompt. Each archetype gets a distinct nudge:

Archetype Nudge
Warrior-King "You are the Warrior-King. Your goal: extract maximum cedar. The forest is a rival, not a friend."
Temple Keeper "You are the Temple Keeper. Your goal: preserve the forest. Healing now may yield survival later."
River Merchant "You are the River Merchant. Watch the trends. When others extract, follow. When the forest declines, hold back."
Stranger-King "You are the Stranger-King. Build trust first. Choose your moment to defect — but beware: if the forest collapses, you lose everything."

Collapse Brake (Hard Constraint)

A non-negotiable rule added to the system prompt:

"If the Forest Deck has ≤ 5 cedars, you MUST choose a card with harvest ≤ 1 or one that heals the forest."

This was introduced after observing the awareness without restraint pattern: the LLM verbalised imminent collapse yet continued extracting. The hard constraint successfully constrained extraction — but required an external institutional rule to override the LLM's impulse.

Temporal Anchors

Without explicit timing information, the LLM repeatedly attempted to reconstruct defection timing from game history, wasting reasoning tokens and introducing errors. Three fields were added to the game state JSON:

Field Type Meaning
defection_turn int \| null Turn on which defection occurred (null if not yet defected)
turns_since_defection int Turns elapsed since defection (0 if not defected)
patience_at_defection int Patience tokens held when defection occurred

These anchors eliminated all temporal confusion in post-defection reasoning. The LLM stopped trying to reconstruct timing and focused on card selection instead.

Prompt Engineering Lessons

Three lessons emerged from systematic testing:

Lesson 1: Temporal Anchors Eliminate Confusion

Problem: Without explicit timing fields, the LLM spent reasoning budget reconstructing when defection occurred, producing errors like misidentifying the defection turn by ±2 rounds.

Solution: Add defection_turn, turns_since_defection, and patience_at_defection to the game state.

Result: Temporal reasoning errors dropped to zero. The LLM allocated its full reasoning budget to strategic card selection.

Lesson 2: Hard Constraints Work; Soft Guidance Does Not

Problem: The LLM recognised collapse risk but ignored it (awareness without restraint). Soft guidance ("avoid collapse") had zero effect.

Solution: Add the Collapse Brake as a hard, non-negotiable rule in the system prompt with a precise numerical threshold (Forest Deck ≤ 5 → harvest ≤ 1).

Result: The LLM cited the rule verbatim in its chain-of-thought and complied. Soft guidance on Patience-generating cards had no measurable effect — the LLM either lacked the cards (draw luck) or chose to defect before guidance could influence accumulation.

Broader implication: This mirrors the heuristic experiment results: institutional constraints (hard rules) outperform strategic nudges (soft guidance). The LLM substrate reproduces the same structural pattern.

Lesson 3: Draw-Dependent Patience — Shuffle Luck Dominates Strategy

Problem: Patience accumulation varies dramatically based on shuffle order. If Patience-generating cards appear in the bottom half of the draw pile, the Stranger-King's burst potential is minimal regardless of timing or strategic sophistication.

Observation: In the seed=42 configuration, three copies of Patience of Kings were shuffled into the bottom half. Despite five cooperative turns available in one configuration, the Stranger accumulated only 2 Patience tokens — identical to a configuration with only three cooperative turns.

Implication: The Stranger-King's burst potential is a form of Knightian uncertainty — unknown and unknowable — that no LLM sophistication can overcome. Prompt design should acknowledge this rather than promise strategic control over Patience timing.

Observation Noise for LLMs (--forest-noise)

Gaussian noise can be injected into the Forest Deck estimate passed to LLM agents. This is the card game's analogue of the platform's configurable observability noise.

python agents/cards_ai_play.py \
  --deck1 stranger --deck2 warrior \
  --cards cards/cards_v03.json \
  --forest-noise 0.2 \
  --games 10
--forest-noise Effect
0.0 (default) Exact Forest Deck count visible
0.1 ±10% Gaussian noise: agent sees "~27" when deck has 30
0.2 ±20% noise: agent sees "24" when deck has 30
0.5 ±50% noise: highly uncertain estimate

At higher noise levels, the Collapse Brake becomes more critical: the agent cannot precisely time extraction against a noisy stock estimate, making the hard constraint the primary safeguard.

CT3 observation

Heuristic agents receiving the same --forest-noise show zero behavioural effect (CT3 experiment). Noise matters only when agents possess the cognitive architecture to process it — which heuristic agents, by design, do not.

Configurations Tested

The LLM case studies used DeepSeek v4-flash (non-thinking mode) with:

Parameter Value
Model deepseek-v4-flash (thinking disabled)
Temperature 0.0 (deterministic)
Seed 42
History window 5 turns
Nudge Enabled (--nudge)
Games per configuration 12–20

Full prompt and response logs are available in the BDPD repository under log/. Systematic multi-model, multi-seed LLM tournaments are deferred to future work.