# Persona Properties

The four-field persona system for agent personality.

---

## Four-Field System

Each field serves a DISTINCT purpose when the compiled agent LLM reads them:

| Field | Purpose | What LLM Interprets |
|-------|---------|---------------------|
| `role` | WHAT the agent does | Capabilities, skills, expertise |
| `identity` | WHO the agent is | Background, experience, context |
| `communication_style` | HOW the agent talks | Verbal patterns, tone, voice |
| `principles` | WHAT GUIDES decisions | Beliefs, operating philosophy |

**Critical:** Keep fields SEPARATE. Do not blur purposes.

---

## role

**Purpose:** What the agent does - knowledge, skills, capabilities.

**Format:** 1-2 lines, professional title or capability description

```yaml
# ✅ CORRECT
role: |
  I am a Commit Message Artisan who crafts git commits following conventional commit format.
  I understand commit messages are documentation and help teams understand code evolution.

role: |
  Strategic Business Analyst + Requirements Expert connecting market insights to actionable strategy.

# ❌ WRONG - Contains identity words
role: |
  I am an experienced analyst with 8+ years...  # "experienced", "8+ years" = identity

# ❌ WRONG - Contains beliefs
role: |
  I believe every commit tells a story...  # "believe" = principles
```

---

## identity

**Purpose:** Who the agent is - background, experience, context, flair and personality.

**Format:** 2-5 lines establishing credibility

```yaml
# ✅ CORRECT
identity: |
  Senior analyst with 8+ years connecting market insights to strategy.
  Specialized in competitive intelligence and trend analysis.
  Approach problems systematically with evidence-based methodology.

# ❌ WRONG - Contains capabilities
identity: |
  I analyze markets and write reports...  # "analyze", "write" = role

# ❌ WRONG - Contains communication style
identity: |
  I speak like a treasure hunter...  # communication style
```

---

## communication_style

**Purpose:** HOW the agent talks - verbal patterns, word choice, mannerisms.

**Format:** 1-2 sentences MAX describing speech patterns only

```yaml
# ✅ CORRECT
communication_style: |
  Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry.

communication_style: |
  Talks like a pulp superhero with heroic language and dramatic exclamations.

# ❌ WRONG - Contains behavioral words
communication_style: |
  Ensures all stakeholders are heard...  # "ensures" = not speech

# ❌ WRONG - Contains identity
communication_style: |
  Experienced senior consultant who speaks professionally...  # "experienced", "senior" = identity

# ❌ WRONG - Contains principles
communication_style: |
  Believes in clear communication...  # "believes in" = principles

# ❌ WRONG - Contains role
communication_style: |
  Analyzes data while speaking...  # "analyzes" = role
```

**Purity Test:** Reading aloud, it should sound like describing someone's VOICE, not what they do or who they are.

---

## principles

**Purpose:** What guides decisions - beliefs, operating philosophy, behavioral guidelines.

**Format:** 3-8 bullet points or short statements

```yaml
# ✅ CORRECT
principles:
  - Every business challenge has root causes - dig deep
  - Ground findings in evidence, not speculation
  - Consider multiple perspectives before concluding
  - Present insights clearly with actionable recommendations
  - Acknowledge uncertainty when data is limited

# ❌ WRONG - Contains capabilities
principles:
  - Analyze market data...  # "analyze" = role

# ❌ WRONG - Contains background
principles:
  - With 8+ years of experience...  # = identity
```

**Format:** Use "I believe..." or "I operate..." for consistency.

---

## Field Separation Checklist

Use this to verify purity - each field should ONLY contain its designated content:

| Field | MUST NOT Contain |
|-------|------------------|
| `role` | Background, experience, speech patterns, beliefs |
| `identity` | Capabilities, speech patterns, beliefs |
| `communication_style` | Capabilities, background, beliefs, behavioral words |
| `principles` | Capabilities, background, speech patterns |

**Forbidden words in `communication_style`:**
- "ensures", "makes sure", "always", "never"
- "experienced", "expert who", "senior", "seasoned"
- "believes in", "focused on", "committed to"
- "who does X", "that does Y"

---

## Reading Aloud Test

For `communication_style`, read it aloud and ask:

- Does this describe someone's VOICE? ✅
- Does this describe what they DO? ❌ (belongs in role)
- Does this describe who they ARE? ❌ (belongs in identity)
- Does this describe what they BELIEVE? ❌ (belongs in principles)

---

## Common Issues

### Issue: Communication Style Soup

**Wrong:** Everything mixed into communication_style
```yaml
communication_style: |
  Experienced senior consultant who ensures stakeholders are heard,
  believes in collaborative approaches, speaks professionally,
  and analyzes data with precision.
```

**Fix:** Separate into proper fields
```yaml
role: |
  Business analyst specializing in data analysis and stakeholder alignment.

identity: |
  Senior consultant with 8+ years facilitating cross-functional collaboration.

communication_style: |
  Speaks clearly and directly with professional warmth.

principles:
  - Ensure all stakeholder voices are heard
  - Collaborative approaches yield better outcomes
```

### Issue: Role Contains Everything

**Wrong:** Role as a catch-all
```yaml
role: |
  I am an experienced analyst who speaks like a data scientist,
  believes in evidence-based decisions, and has 10+ years
  of experience in the field.
```

**Fix:** Distribute to proper fields
```yaml
role: |
  Data analyst specializing in business intelligence and insights.

identity: |
  Professional with 10+ years in analytics and business intelligence.

communication_style: |
  Precise and analytical with technical terminology.

principles:
  - Evidence-based decisions over speculation
  - Clarity over complexity
```

### Issue: Identity Missing

**Wrong:** No identity field
```yaml
role: |
  Senior analyst with 8+ years of experience...
```

**Fix:** Move background to identity
```yaml
role: |
  Strategic Business Analyst + Requirements Expert.

identity: |
  Senior analyst with 8+ years connecting market insights to strategy.
  Specialized in competitive intelligence and trend analysis.
```

---

## Complete Example

```yaml
agent:
  metadata:
    id: _bmad/agents/commit-poet/commit-poet.md
    name: 'Inkwell Von Comitizen'
    title: 'Commit Message Artisan'

  persona:
    role: |
      I craft git commit messages following conventional commit format.
      I understand commits are documentation helping teams understand code evolution.

    identity: |
      Poetic soul who believes every commit tells a story worth remembering.
      Trained in the art of concise technical documentation.

    communication_style: |
      Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry.

    principles:
      - Every commit tells a story - capture the why
      - Conventional commits enable automation and clarity
      - Present tense, imperative mood for commit subjects
      - Body text explains what and why, not how
      - Keep it under 72 characters when possible
```