Chapter 2: Custom Personas

Learning Objectives

By the end of this chapter you will be able to:

1. Write a complete R.I.S.C.E.A.R. persona specification in YAML.
2. Validate your persona against the FCC JSON schema.
3. Register custom personas alongside the core catalog.
4. Design persona dimensions, Discernment Matrix ratings, and Design Target Factors.
5. Test persona specifications programmatically and catch common mistakes.

---

The ER diagram below shows the four data classes that make up a persona definition: PersonaSpec, its required RISCEARSpec, and the optional DimensionProfile and Constitution attachments.

erDiagram
    PersonaSpec {
        string id PK
        string name
        string category
        string fcc_phase
        string description
    }
    RISCEARSpec {
        string role
        string input
        string style
        string constraints
        string expected_output
        string archetype
        list responsibilities
        list role_skills
        list role_collaborators
        list adoption_checklist
    }
    DimensionProfile {
        string persona_id FK
        int total_dimensions
    }
    Constitution {
        list hard_stop_rules
        list mandatory_patterns
        list preferred_patterns
    }
    PersonaSpec ||--|| RISCEARSpec : has
    PersonaSpec ||--o| DimensionProfile : may_have
    PersonaSpec ||--o| Constitution : may_have

The separation of RISCEAR from Dimensions and Constitution is deliberate: RISCEAR governs what the persona produces, while the optional blocks govern how behaviour is profiled and constrained. You can ship a fully functional persona with only the required spec.

Anatomy of a Persona YAML

Every persona is defined in a YAML file that conforms to the persona JSON schema at src/fcc/data/schemas/persona_schema.json. Here is a complete example for a custom "Domain Expert" persona:

personas:
  - id: domain_expert
    name: "Domain Expert"
    category: stakeholder
    fcc_phase: find
    description: >
      A subject-matter expert who provides deep domain knowledge during the
      Find phase. Translates business context into structured requirements
      that downstream personas can act on.

    spec:
      role: >
        Provide authoritative domain knowledge and translate business
        requirements into technical specifications.
      input: >
        Project brief, stakeholder interviews, market context from the
        Research Analyst.
      style: >
        Precise, structured, uses domain-specific terminology with
        definitions. Avoids jargon without explanation.
      constraints:
        - "Only provide information within your declared domain of expertise."
        - "Flag uncertainty explicitly -- never present assumptions as facts."
        - "Include confidence levels (high/medium/low) for all assertions."
      expected_output: >
        A structured requirements document with numbered requirements,
        acceptance criteria, priority levels, and confidence assessments.
      archetype: "The Specialist"
      responsibilities:
        - "Validate that project goals align with domain realities."
        - "Identify domain-specific risks and constraints."
        - "Translate stakeholder language into technical requirements."
        - "Review Create-phase outputs for domain accuracy."
      role_skills:
        - "Domain modeling"
        - "Requirements elicitation"
        - "Risk assessment"
        - "Stakeholder communication"
      role_collaborators:
        upstream:
          - research_analyst
        downstream:
          - software_architect
          - strategy_lead
        peers:
          - product_owner
      role_adoption_checklist:
        - "Load the project brief and stakeholder interview transcripts."
        - "Identify the primary domain and any adjacent domains."
        - "Set confidence threshold to medium or higher."
        - "Use the structured requirements template."

    tags:
      capability: requirements
      category: stakeholder
      supercategory: planning

Let us walk through each section.

The id Field

The persona ID is the primary key. It must be unique across the entire registry -- core personas, plugin personas, and your custom personas. Use snake_case by convention. If you use an ID that matches a core persona, your definition overrides the core one.

The fcc_phase Field

This declares which phase of the FCC cycle the persona primarily operates in: find, create, or critique. Some personas operate in multiple phases, but the primary phase determines their default position in workflow graphs.

The spec Object

This is the R.I.S.C.E.A.R. specification. All ten components are required:

1. role -- one or two sentences stating what the persona does.
2. input -- what the persona needs to begin work.
3. style -- how the persona communicates (prose style, format, conventions).
4. constraints -- a list of hard rules the persona must follow.
5. expected_output -- the concrete artifact type and format.
6. archetype -- the behavioral archetype (from the 37-archetype vocabulary).
7. responsibilities -- a list of specific duties.
8. role_skills -- a list of technical and domain skills.
9. role_collaborators -- upstream, downstream, and peer persona IDs.
10. role_adoption_checklist -- steps for activating the persona.

The tags Object

Tags use a three-level hierarchy: capability, category, and supercategory. These feed into the governance tag registry for classification and compliance reporting. The full tag vocabulary is defined in src/fcc/data/governance/tag_registry.yaml.

Validation

After writing your YAML, validate it:

# CLI validation
fcc validate --persona domain_expert

# Or validate all personas in the project
fcc validate

The validator checks:

• All required fields are present.
• The id is valid (snake_case, no spaces).
• The fcc_phase is one of the three valid values.
• All role_collaborators reference personas that exist in the registry.
• Tags reference valid entries in the tag registry.
• The file is syntactically valid YAML.

Programmatic Validation

For CI pipelines or custom tooling:

from fcc.scenarios.validator import FCCValidator
from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry()
registry.load_all()

validator = FCCValidator.from_registry(registry)
errors = validator.validate_persona("domain_expert")

if errors:
    for error in errors:
        print(f"  {error.field}: {error.message}")
else:
    print("Persona is valid.")

Adding Persona Dimensions

To give your persona a dimension profile, add a dimensions section:

    dimensions:
      core:
        expertise_depth: 7
        expertise_breadth: 4
        analytical_rigor: 6
      behavioral:
        risk_tolerance: 3
        initiative: 5
        thoroughness: 7
      communication:
        verbosity: 4
        formality: 6
        persuasion: 5
      decision_making:
        analytical_vs_intuitive: 6
        speed_vs_thoroughness: 3

Each dimension is rated on a 1--7 scale. You do not need to fill in all 56 dimensions -- missing dimensions default to the category median. The DimensionRegistry manages the full vocabulary of dimensions and their default values.

Adding Discernment Matrix and Design Target Factors

For richer behavioral modeling, add these two optional sections:

    discernment_matrix:
      humility: 6
      professional_background: 7
      curiosity: 5
      taste: 5
      inclusivity: 6
      responsibility: 7

    design_target_factors:
      optimism: 4
      social_connectivity: 5
      influence: 6
      diversity_appreciation: 6
      curiosity: 5
      leadership: 4

These ratings influence how the simulation engine generates persona-appropriate prompts. A persona with high humility and low influence will communicate differently than one with low humility and high influence, even if their R.I.S.C.E.A.R. roles are similar.

Champion Personas

To create a champion persona that coordinates a team, add the champion_of and orchestrates fields:

  - id: domain_champion
    name: "Domain Champion"
    category: champion
    fcc_phase: find
    champion_of: stakeholder
    orchestrates:
      - domain_expert
      - product_owner
      - business_sponsor
    spec:
      role: >
        Coordinate the stakeholder team, sequence their contributions,
        resolve conflicts, and escalate issues to governance.
      # ... rest of R.I.S.C.E.A.R. spec

Champions inherit the constitutions of all personas they orchestrate (see Book 1, Chapter 4). This means a Domain Champion is subject to all the governance rules that apply to the Domain Expert, Product Owner, and Business Sponsor, plus any champion-specific rules.

Common Mistakes

Having reviewed hundreds of custom persona definitions, here are the most common mistakes:

1. Vague Role statements. "Helps with the project" is not a role. A role must state what the persona does concretely.
2. Missing constraints. Every persona should have at least 2--3 constraints that prevent scope creep.
3. Circular collaborator references. If Persona A lists Persona B as upstream and Persona B lists Persona A as upstream, the cross-reference matrix will flag a cycle.
4. Overloaded responsibilities. If a persona has more than 8 responsibilities, consider splitting it into two personas.
5. Archetype mismatch. The archetype should match the role. A "Guardian" archetype paired with a "Create" phase role is a red flag.

Testing Personas

Write tests for your custom personas:

"""Tests for custom domain_expert persona."""
import pytest
from fcc.personas.registry import PersonaRegistry


@pytest.fixture
def registry():
    reg = PersonaRegistry()
    reg.load_all()
    return reg


def test_domain_expert_exists(registry):
    persona = registry.get("domain_expert")
    assert persona is not None


def test_domain_expert_phase(registry):
    persona = registry.get("domain_expert")
    assert persona.fcc_phase == "find"


def test_domain_expert_collaborators(registry):
    persona = registry.get("domain_expert")
    assert "research_analyst" in persona.spec.role_collaborators.upstream
    assert "software_architect" in persona.spec.role_collaborators.downstream


def test_domain_expert_has_constraints(registry):
    persona = registry.get("domain_expert")
    assert len(persona.spec.constraints) >= 2

These tests verify that your persona loads correctly, has the right phase, declares valid collaborators, and includes sufficient constraints.

Key Takeaways

• Persona YAML files follow a strict schema with 10 R.I.S.C.E.A.R. components plus optional dimensions.
• Validate early and often using fcc validate or the programmatic validator.
• Custom personas merge with the core catalog; local definitions override core ones by ID.
• Champions coordinate teams and inherit governance rules from orchestrated personas.
• Persona dimensions, Discernment Matrix, and Design Target Factors add behavioral depth.
• Test your personas as part of your CI pipeline to catch regressions.

Cross-References

• Chapter 3: Workflow Design -- place your personas in a workflow graph
• FCC Guidebook, Chapter 3 -- full R.I.S.C.E.A.R. reference
• Notebook 02: Persona Explorer -- interactive browsing
• Book 1, Chapter 2: The Persona Mental Model -- conceptual foundation

---

← Chapter 1: Project Setup | Next: Chapter 3 -- Workflow Design →