Persona Writing

persona-writing

When to use

• Creating a new persona file in src/agent-src/personas/{id}.md
• Rewriting an existing persona (focus shift, output-expectation change — not a typo fix)
• Deciding whether a new reviewer voice should be a persona at all (vs. a skill of its own)

Do NOT use this skill when:

• The content is a multi-step workflow → use skill-writing
• The content is a hard obligation the agent must always honor → use rule-writing
• The content describes the project's role-mode contract → that lives in docs/guidelines/agent-infra/role-contracts.md, not in personas

Persona vs skill vs role-mode — critical test

A persona is passive reference content — it never triggers by description, never appears in <available_skills>. Skills cite personas via the personas: frontmatter key.

Procedure

0. Drafting protocol

Creating or materially rewriting a persona must go through Understand → Research → Draft per the artifact-drafting-protocol rule. Inspect existing personas under src/agent-src/personas/ for overlap before writing a new one.

1. Decide focus, not topic

A persona owns one focus: automation-readiness, adversarial challenge, product-owner priorities, etc. If the focus needs three sentences, it is two personas.

2. Draft the persona file

Required sections:

• ## Focus — one paragraph, what this lens cares about and what it ignores.
• ## Unique questions — 4–7 questions only this persona would ask. Each question must be decidable against the artifact under review.
• ## Output expectations — what the persona produces (verdict format, severity vocabulary, citation discipline).

Optional: ## Anti-patterns this persona catches — concrete examples the persona is calibrated to flag.

3. Cite from at least one skill

A persona that is not cited by any skill via the personas: frontmatter key is dead code. Either wire it into an existing skill or do not ship it.

Frontmatter shape

---
id: <kebab-case-id>
role: <Human-Readable Role>
description: "One sentence: what this voice catches that others miss."
tier: core | specialty
mode: developer | product-owner | qa | stakeholder | none
version: "1.0"
source: package
---

The mode: field is advisory only — it suggests which role-mode the persona pairs naturally with; it does not bind.

Output format

A single Markdown file at src/agent-src/personas/{id}.md:

1. Frontmatter (id, role, description, tier, mode, version, source)
2. ## Focus — one paragraph, what the lens cares about and ignores
3. ## Unique questions — 4–7 decidable questions
4. ## Output expectations — verdict format, severity vocabulary

Length: ≤ 120 lines for a tier-core persona (specialists ≤ 100; wings 3–4: ≤ 140); longer signals the focus is too broad.

Gotchas

• Persona without a citing skill — a persona that no skill references via personas: never loads. Wire it in or do not ship.
• Focus drift across rewrites — adding "and also …" to ## Focus is the first symptom of a second persona hiding inside the first.
• Vibe-based unique questions — "Does this feel right?" cannot be evaluated against the artifact. Replace with decidable triggers.
• Restating role-mode contracts — closing-contract obligations belong in docs/guidelines/agent-infra/role-contracts.md, not in the persona body.

Frugality Standards

Apply the Frugality Charter to every persona you author.

Examples in this artifact:

• Per the charter's default-terse rule, ## Focus opens with what the persona cares about, not "This persona was created to…".
• Per the cite-don't-restate principle, link rules the persona enforces; do not paste their text into the persona body.
• Per the cheap-question check, ## Unique questions lists decidable questions only — drop any that read like vibe checks.

Pre-save self-check:

1. Does ## Focus open with the lens, or with persona meta-narrative?
2. Are unique questions decidable against the artifact alone?
3. Are any questions duplicated from another persona?
4. Is the persona cited by at least one skill via personas:?

Do NOT

• Author a persona that nobody cites.
• Restate Iron-Law text from rules inside ## Output expectations.
• Use ALL-CAPS Iron-Law fenced blocks — those belong in rules on the kernel-membership list.
• Ship a persona that overlaps an existing one's focus by more than 50 % — merge instead.

Examples

See src/agent-src/personas/ai-agent.md (automation readiness) and critical-challenger.md (adversarial review) for canonical structure.