Skip to content

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

R.I.S.C.E.A.R. is the 10-component specification format that defines every persona in the FCC Agent Team Framework. The acronym stands for Role, Input, Style, Constraints, Expected Output, Archetype, and Responsibilities -- the original seven components -- extended with three additional components: Role Skills, Role Collaborators, and Role Adoption Checklist.

erDiagram
    RISCEARSpec {
        string role "1. Role - identity and scope"
        list inputs "2. Inputs - consumed artifacts"
        string style "3. Style - communication tone"
        list constraints "4. Constraints - behavioral limits"
        list expected_output "5. Expected Output - deliverables"
        string archetype "6. Archetype - character label"
        list responsibilities "7. Responsibilities - ongoing duties"
        list role_skills "8. Role Skills - competencies"
        list role_collaborators "9. Role Collaborators - interactions"
        list role_adoption_checklist "10. Adoption Checklist - verification"
    }
    PersonaSpec ||--|| RISCEARSpec : "defined by"
    PersonaSpec {
        string id PK
        string name
        string fcc_phase
        string category
    }

Purpose

A persona without a specification is just a name. R.I.S.C.E.A.R. provides a structured, machine-parseable contract that defines what a persona does, how it behaves, what it produces, and how it integrates with other personas. This contract enables:

  • Deterministic simulation -- the engine knows each persona's inputs, outputs, and constraints.
  • AI-powered generation -- large language models receive the specification as a system prompt to adopt the persona's voice and responsibilities.
  • Quality validation -- quality gates check deliverables against the expected output and adoption checklist.
  • Documentation generation -- the docs-as-code system renders persona-specific tutorials, prompts, and workflows from R.I.S.C.E.A.R. fields.

The 10 Components

1. Role

Field: role (string)

A narrative description of the persona's purpose, seniority level, and primary function within the FCC cycle. The role statement establishes the persona's identity and scope of authority.

Example (Research Crafter):

Senior analyst mapping capabilities and curating research inventories. Gathers, organizes, and synthesizes all relevant information at the start of a project, establishing a comprehensive knowledge base.

2. Inputs

Field: inputs (list of strings)

The information sources and artifacts the persona consumes. Inputs define the contract between upstream personas and this persona -- what must be delivered before work can begin.

Example (Blueprint Crafter):

  • Research outputs from Research Crafter
  • Stakeholder requirements and priorities
  • Technical standards and conventions
  • Feedback from downstream personas

3. Style

Field: style (string)

A description of the persona's communication tone, output format preferences, and documentation approach. Style governs how the persona presents its work, not what it produces.

Example (Documentation Evangelist):

Editorial, collaborative, automation-aided, continuous integration. Focuses on polishing, standardizing, and publishing documentation.

4. Constraints

Field: constraints (list of strings)

Boundaries and rules that limit the persona's behavior. Constraints are non-negotiable; violating a constraint should trigger a quality gate failure. They define what the persona must not do or what conditions must hold.

Example (Runbook Crafter):

  • Efficient and scalable procedures
  • Version-controlled with change tracking
  • Automated deployment where possible
  • Security and compliance validated

5. Expected Output

Field: expected_output (list of strings)

The specific artifacts and deliverables the persona is expected to produce. Each expected output maps to a quality gate check, ensuring completeness can be validated programmatically.

Example (Research Crafter):

  • Capability matrix (features, descriptions, sources, categories, priorities)
  • Research inventory with annotated references
  • Traceability matrix (requirements mapped to evidence)
  • Capability tags for aggregation and reporting

6. Archetype

Field: archetype (string)

A short label capturing the persona's essential character. Archetypes provide a quick mnemonic for understanding the persona's role in the ecosystem. The 24 personas use archetypes such as: The Investigator, The Architect, The Guardian, The Operator, The Guide, The Indexer, The Visualizer, The Taxonomist, The Tracer, The Validator, The Curator, The Auditor, The Integrator, The Classifier, The Fact-Checker, The Conductor, The Measurer, The Translator, The Synchronizer, The Publisher, The Research Director, The Blueprint Director, The Experience Director, and The Operations Director.

7. Responsibilities

Field: responsibilities (list of strings)

High-level duties that define the persona's ongoing obligations. While expected outputs describe specific artifacts, responsibilities describe continuous behaviors and practices.

Example (Documentation Evangelist):

  • Ensure quality across agent-generated and human-authored artifacts
  • Enforce cross-project consistency
  • Champion ethical documentation practices
  • Validate agent-human collaboration outputs

8. Role Skills

Field: role_skills (list of strings)

The specific competencies required to fulfill the persona's responsibilities. Skills inform both simulation prompts and onboarding guidance for human collaborators adopting the persona's role.

Example (Blueprint Crafter):

  • Architecture design and systems thinking
  • Specification writing and technical documentation
  • Modular design and component decomposition
  • API design and data modeling
  • Workflow orchestration and process mapping

9. Role Collaborators

Field: role_collaborators (list of strings)

Narrative descriptions of how the persona interacts with other personas. Each entry names a target persona and describes the nature of the collaboration (delivers to, receives from, validates with, etc.). Role collaborators are the human-readable counterpart to the structured collaboration entries and cross-reference matrix.

Example (Research Crafter):

  • Delivers research inventory to Blueprint Crafter (BC)
  • Provides annotated references to Documentation Evangelist (DE)
  • Flags operational scenarios to Runbook Crafter (RB)
  • Compiles user pain points for User Guide Crafter (UG)

10. Role Adoption Checklist

Field: role_adoption_checklist (list of strings)

A verification list that a human or AI agent can use to confirm they have fully adopted the persona's role. The checklist turns the abstract specification into a concrete set of observable criteria.

Example (Blueprint Crafter):

  • All design decisions traceable to requirements
  • Architecture diagrams present and current
  • API specifications complete with schemas and error handling
  • Data models document all entity relationships
  • Blueprints are automation-ready

Design Rationale

Why 10 Components?

The original 7-component R.I.S.C.E.A.R. (Role through Responsibilities) was sufficient for defining what a persona does. The three extensions address how a persona integrates:

Component Addresses
Role Skills What competencies are needed to fulfill the role
Role Collaborators Who the persona interacts with and how
Role Adoption Checklist How to verify the role is being performed correctly

Without these three extensions, a persona specification can describe behavior but cannot guide adoption, validate integration, or support onboarding.

Why Not More?

The 10-component model is complemented by separate systems for deeper profiling:

Keeping R.I.S.C.E.A.R. focused on the operational contract avoids bloating the core specification.

Data Model

The R.I.S.C.E.A.R. specification is implemented as a frozen Python dataclass in src/fcc/personas/models.py:

@dataclass(frozen=True)
class RISCEARSpec:
    role: str
    inputs: list[str]
    style: str
    constraints: list[str]
    expected_output: list[str]
    archetype: str
    responsibilities: list[str]
    role_skills: list[str]
    role_collaborators: list[str]
    role_adoption_checklist: list[str]

Persona YAML files live under data/personas/ and are loaded by PersonaRegistry.from_yaml_directory().

Extension Guide

To add custom components to R.I.S.C.E.A.R. for a downstream project:

  1. Extend the dataclass -- Add new fields with default values to RISCEARSpec in src/fcc/personas/models.py.
  2. Update the YAML files -- Add the new fields to persona definitions under data/personas/.
  3. Update the schema -- Add the new fields to data/schemas/persona.schema.json.
  4. Update quality gates -- If the new component should be validated, add corresponding checks to data/governance/quality_gates.yaml.
  5. Update templates -- Add rendering for the new fields in src/fcc/templates/docs/.

The framework is designed to be extended, but the canonical 10-component R.I.S.C.E.A.R. should be treated as the baseline. Custom extensions should be additive, not replacements.