Skip to content

Understanding Personas

This tutorial explains what an FCC persona is, how the R.I.S.C.E.A.R. specification works, the five categories of personas, and how to read a persona YAML definition file.

What is a PersonaSpec?

A PersonaSpec is a Python dataclass that defines everything about an FCC agent persona: its identity, phase assignment, R.I.S.C.E.A.R. specification, documentation context, deliverables, and collaboration relationships.

Every persona in FCC is an instance of PersonaSpec, loaded from YAML files in the data/personas/ directory. The PersonaRegistry class manages these specs, providing lookup by ID, name, phase, category, and champion relationship.

from fcc.personas.registry import PersonaRegistry

# Load all personas from the data directory
registry = PersonaRegistry.from_yaml_directory("data/personas/")

# Look up by ID
rc = registry.get("RC")
print(rc.name)       # "Research Crafter"
print(rc.fcc_phase)  # "Find"
print(rc.category)   # "core"

# List all personas in a category
core_personas = registry.by_category("core")
# [RC, BC, DE, RB, UG]

The R.I.S.C.E.A.R. Specification

R.I.S.C.E.A.R. is the 10-component specification format that defines how each persona behaves. The name is an acronym for its components:

The 10 Components

# Component Purpose Example (RC)
1 Role What the persona does "Senior analyst mapping capabilities and curating research inventories"
2 Inputs What data the persona consumes Source code, architecture docs, stakeholder feedback
3 Style How the persona communicates "Analytical, structured lists, annotated references, version-controlled"
4 Constraints Rules the persona must follow Relevant to scope, no duplication, tagged with capability IDs
5 Expected Output What the persona produces Capability matrix, research inventory, traceability matrix
6 Archetype The persona's behavioral model "The Investigator"
7 Responsibilities Ongoing duties Curate knowledge bases, bridge agent-human gaps
8 Role Skills Technical competencies Research methodology, data analysis, taxonomy design
9 Role Collaborators Who the persona works with Delivers to BC, provides references to DE
10 Role Adoption Checklist Verification items Research inventory verified, capability matrix complete

The first six components (R-I-S-C-E-A) form the core specification. The last four (R-S-C-A, standing for Responsibilities, Role Skills, Role Collaborators, Role Adoption Checklist) are extended components that were added to support the full 24-persona framework.

Accessing R.I.S.C.E.A.R. in Code

The RISCEARSpec dataclass holds all 10 components:

rc = registry.get("RC")
riscear = rc.riscear

print(riscear.role)              # Role description
print(riscear.inputs)            # List of input types
print(riscear.style)             # Communication style
print(riscear.constraints)       # List of constraints
print(riscear.expected_output)   # List of expected outputs
print(riscear.archetype)         # Behavioral archetype
print(riscear.responsibilities)  # List of responsibilities
print(riscear.role_skills)       # List of skills
print(riscear.role_collaborators)# List of collaborator descriptions
print(riscear.role_adoption_checklist)  # List of checklist items

The Five Categories

FCC personas are organized into five categories, each serving a distinct function in the framework:

1. Core (5 personas)

The essential FCC cycle. These five personas are present in all three workflow graphs.

ID Name Phase Archetype
RC Research Crafter Find The Investigator
BC Blueprint Crafter Create The Architect
DE Documentation Evangelist Critique The Guardian
RB Runbook Crafter Create The Operator
UG User Guide Crafter Create The Guide

2. Integration (7 personas)

Specialized capabilities that extend the core cycle with indexing, validation, traceability, and compliance.

ID Name Phase Archetype
CIA Catalog Indexer Architect Find The Indexer
UMC UI Mockup Crafter Create The Visualizer
STE Semantic Taxonomy Engineer Find The Taxonomist
TS Traceability Specialist All The Tracer
BV Blueprint Validator Critique The Validator
RIC Research Inventory Crafter Find The Curator
GCA Governance Compliance Auditor Critique The Auditor

3. Governance (3 personas)

Data governance, privacy classification, and AI content fact-checking.

ID Name Phase Archetype
DGS Data Governance Specialist All The Integrator
PTE Privacy Taxonomy Engineer Create The Classifier
AMS Anti-fact Mitigation Specialist Critique The Fact-Checker

4. Stakeholder (5 personas)

Cross-team coordination, metrics, executive communication, and content publishing.

ID Name Phase Archetype
CO Collaboration Orchestrator All The Conductor
SMC SAFe Metrics Crafter Critique The Measurer
EC Executive Communicator Create The Translator
RS Roadmap Synchronizer Find The Synchronizer
SCP Stakeholder Content Publisher Create The Publisher

5. Champion (4 personas)

Elevated personas that orchestrate teams of base personas. Each champion has a champion_of field linking to the base persona it elevates, and an orchestrates list specifying which personas it coordinates.

ID Name Champion Of Orchestrates
RCHM Research Crafter Champion RC RC, CIA, STE, RIC
BCHM Blueprint Crafter Champion BC BC, BV, UMC, RIC
UGCH User Guide Crafter Champion UG UG, SCP, EC
RBCH Runbook Crafter Champion RB RB, GCA, TS 
# Working with champions
champions = registry.champions()
for champ in champions:
    print(f"{champ.id} orchestrates {champ.orchestrates}")
    base = registry.base_of(champ.id)
    print(f"  Champion of {base.name}")

Reading a Persona YAML File

Persona definitions live in YAML files under data/personas/. Here is the structure of the Research Crafter (RC) as an example:

personas:
  - id: RC
    name: Research Crafter
    fcc_phase: Find
    role_title: Senior Analyst
    color: "#4CAF50"
    riscear:
      role: >-
        Senior analyst mapping capabilities and curating research inventories.
      inputs:
        - Source code and architecture docs
        - Code reviews and technical standards
        - Runbooks and operational procedures
        - Stakeholder feedback and requirements
      style: >-
        Analytical, structured lists, annotated references, version-controlled.
      constraints:
        - Relevant to project scope
        - No duplication of existing research
        - Accessible in shared repository
        - Tagged with capability IDs
      expected_output:
        - Capability matrix
        - Research inventory with annotated references
        - Traceability matrix
        - Capability tags for aggregation
      archetype: The Investigator
      responsibilities:
        - Curate automatable knowledge bases
        - Bridge agent-human information gaps
        - Map capabilities for architectural runway planning
      role_skills:
        - Research methodology and systematic literature review
        - Data analysis and synthesis
        - Knowledge curation and taxonomy design
      role_collaborators:
        - Delivers research inventory to Blueprint Crafter (BC)
        - Provides annotated references to Documentation Evangelist (DE)
      role_adoption_checklist:
        - Research inventory completeness verified
        - Capability matrix covers all project scope areas
        - All findings tagged with capability IDs
    doc_context:
      primary_action: "research and analysis"
      primary_output: "capability matrix"
      constitution:
        hard_stop:
          - "Never fabricate research sources or citations"
        mandatory:
          - "Tag all findings with capability IDs"
        preferred:
          - "Use structured lists over prose"
    deliverables:
      - name: Capability Matrix
        description: Features, descriptions, sources, categories, priorities
    collaboration:
      - target: BC
        interaction: Delivers research inventory
        direction: downstream

Key Fields

  • id: Short identifier used in workflow graphs and code (e.g., RC, BCHM)
  • fcc_phase: Which FCC phase the persona primarily operates in (Find, Create, Critique, All, or Orchestration)
  • category: Organizational category (core, integration, governance, stakeholder, champion)
  • riscear: The full 10-component R.I.S.C.E.A.R. specification
  • doc_context: Metadata used by the docs-as-code generator, including constitution rules (hard_stop, mandatory, preferred)
  • deliverables: Named artifacts the persona produces
  • collaboration: Directed relationships with other personas (upstream, downstream, peer, both)

Champion-Specific Fields

Champion personas have two additional fields:

  • champion_of: The base persona ID this champion elevates (e.g., RC for RCHM)
  • orchestrates: List of persona IDs this champion coordinates (e.g., [RC, CIA, STE, RIC] for RCHM)

Additional Persona Data

Beyond the core YAML definitions, personas can have:

  • Dimension profiles (data/personas/dimensions/): 56 dimension attributes across 9 categories covering behavioral, communication, cultural, and decision-making patterns
  • Discernment matrices: 6 traits (Humility, Professional Background, Curiosity, Taste, Inclusivity, Responsibility) rated across 7 dimensions
  • Design target factors: 6 factors (Optimism, Social Connectivity, Influence, Diversity Appreciation, Curiosity, Leadership) rated across 7 dimensions

These are loaded automatically when using PersonaRegistry.from_yaml_directory().

Next Steps