Skip to content

Chapter 3: The R.I.S.C.E.A.R. Specification

Origin and Rationale

Every FCC persona needs a precise, machine-readable identity that tells the workflow engine what the persona does, how it communicates, and what it produces. Early persona definitions used free-form descriptions, which made prompts inconsistent and governance enforcement impossible.

The R.I.S.C.E.A.R. specification was created to solve this. It is a 10-component schema that fully specifies a persona's behavioural contract. The name is an acronym of the original seven components (Role, Input, Style, Constraints, Expected output, Archetype, Responsibilities), later extended with three additional components to support skills, collaboration, and adoption tracking.

The specification is implemented as the RISCEARSpec frozen dataclass in src/fcc/personas/models.py and serialized to/from YAML persona definition files in src/fcc/data/personas/.

The entity-relationship diagram below shows how a PersonaSpec owns exactly one RISCEARSpec and how that spec drives prompt generation, governance enforcement, deliverables, and collaboration edges.

erDiagram
    PersonaSpec ||--|| RISCEARSpec : contains
    RISCEARSpec {
        string role "1. What the persona does"
        list inputs "2. Required artifacts"
        string style "3. Communication tone"
        list constraints "4. Hard boundaries"
        list expected_output "5. Deliverable types"
        string archetype "6. Behavioral pattern"
        list responsibilities "7. Specific duties"
        list role_skills "8. Technical skills"
        list role_collaborators "9. Partner persona IDs"
        list role_adoption_checklist "10. Onboarding steps"
    }
    PersonaSpec {
        string id
        string name
        string fcc_phase
        string category
    }
    PersonaSpec ||--o{ Deliverable : produces
    PersonaSpec ||--o{ Collaboration : defines
    RISCEARSpec }|--|| PromptGeneration : drives
    RISCEARSpec }|--|| GovernanceEnforcement : constrains

The rest of this chapter walks each of the ten components in turn and shows how they surface in YAML, in the generated system prompt, and in the governance checks.

The 10 Components

1. Role

A concise statement of the persona's function within the FCC cycle. The role drives the system prompt preamble when the persona is activated.

role: >-
  Evaluate software quality across functional correctness,
  performance, security, and maintainability dimensions.

2. Inputs

A list of artifacts, data, or context that the persona requires to perform its role. Inputs flow from upstream personas via handoff edges in the workflow graph.

inputs:
  - "Source code or architecture diagrams"
  - "Test results and coverage reports"
  - "Quality gate definitions from governance"

3. Style

A description of the persona's communication tone and approach. Style shapes the AI model's voice when generating outputs.

style: >-
  Precise and evidence-based. Uses structured checklists
  and severity ratings. Avoids vague qualifiers.

4. Constraints

Rules the persona must follow. Constraints are injected into the system prompt and enforced during governance gate evaluation.

constraints:
  - "Never approve artifacts that fail hard-stop quality gates"
  - "Always cite the specific gate ID when flagging a violation"
  - "Limit review scope to the deliverables listed in inputs"

5. Expected Output

A list of deliverable types the persona is expected to produce. The action engine uses these to validate that the generated content matches expectations.

expected_output:
  - "Quality assessment report with pass/fail per gate"
  - "Prioritised list of issues with severity ratings"
  - "Recommendations for remediation"

6. Archetype

A short label that categorises the persona's behavioural pattern. Archetypes group personas for cross-reference queries and dashboard displays.

archetype: "Quality Guardian"

The framework uses archetypes to connect personas with similar behavioural patterns. The archetype_interaction_guide.yaml data file defines how archetypes interact, enabling the cross-reference matrix to infer relationships even for newly added personas.

7. Responsibilities

A list of specific duties beyond the general role description. While role is a summary, responsibilities enumerates concrete accountabilities.

responsibilities:
  - "Run static analysis tools and interpret results"
  - "Verify test coverage meets minimum thresholds"
  - "Produce gate-level pass/fail verdicts"
  - "Escalate critical findings to governance personas"

8. Role Skills

Technical and interpersonal skills the persona possesses. Skills influence prompt generation and help the action engine select appropriate execution strategies.

role_skills:
  - "Static analysis (ruff, mypy, bandit)"
  - "Test-coverage measurement (pytest-cov)"
  - "Risk assessment and severity classification"

9. Role Collaborators

Explicit references to other persona IDs that this persona works with. This complements the broader collaboration field on PersonaSpec by listing skill-level partners.

role_collaborators:
  - "BC"   # Business Catalyst — provides requirements context
  - "TCL"  # Tech Catalyst Lead — provides architecture context
  - "GK"   # Governance Keeper — defines quality gates

10. Role Adoption Checklist

A step-by-step checklist for onboarding the persona into a team. Useful for human-in-the-loop collaboration sessions where a human reviewer assumes the persona's role.

role_adoption_checklist:
  - "Review the quality gate registry (governance/quality_gates.yaml)"
  - "Run the existing test suite and note baseline coverage"
  - "Identify the three highest-severity open issues"
  - "Produce a sample quality assessment for one deliverable"

Example Persona Walkthrough

Below is a simplified but complete persona YAML definition showing all 10 R.I.S.C.E.A.R. components in context:

- id: SQC
  name: "Software Quality Critic"
  fcc_phase: critique
  role_title: "Quality Assurance Specialist"
  color: "#E53935"
  category: core
  riscear:
    role: >-
      Evaluate software quality across functional correctness,
      performance, security, and maintainability dimensions.
    inputs:
      - "Source code or architecture diagrams"
      - "Test results and coverage reports"
    style: >-
      Precise and evidence-based. Uses structured checklists.
    constraints:
      - "Never approve artifacts that fail hard-stop quality gates"
      - "Always cite the specific gate ID when flagging a violation"
    expected_output:
      - "Quality assessment report with pass/fail per gate"
      - "Prioritised list of issues with severity ratings"
    archetype: "Quality Guardian"
    responsibilities:
      - "Run static analysis tools and interpret results"
      - "Verify test coverage meets minimum thresholds"
    role_skills:
      - "Static analysis (ruff, mypy, bandit)"
      - "Test-coverage measurement (pytest-cov)"
    role_collaborators:
      - "BC"
      - "GK"
    role_adoption_checklist:
      - "Review the quality gate registry"
      - "Run the existing test suite"
  deliverables:
    - name: "Quality Assessment Report"
      description: "Pass/fail evaluation of each quality gate"
  collaboration:
    - target: "BC"
      interaction: "Receives requirements context"
      direction: upstream
    - target: "GK"
      interaction: "Reports gate verdicts"
      direction: downstream

This YAML is loaded by PersonaSpec.from_dict() and the R.I.S.C.E.A.R. block is parsed by RISCEARSpec.from_dict(). Both produce frozen dataclass instances suitable for indexing, querying, and prompt generation.

How R.I.S.C.E.A.R. Drives Workflow Behaviour

The specification is not merely documentation -- it is consumed at runtime:

  1. Prompt generation. get_action_prompt() in src/fcc/workflow/action_engine.py builds system and user prompts directly from the R.I.S.C.E.A.R. fields. The role and archetype set the identity preamble, style shapes the tone, constraints become hard rules in the system prompt, and expected_output defines what the model should produce.

  2. Governance enforcement. The constraints list is checked by quality gates during the Critique phase. If a persona's output violates a constraint, the gate fails.

  3. Cross-reference wiring. role_collaborators and the collaboration list on PersonaSpec feed into the CrossReferenceMatrix, enabling upstream/downstream/peer queries.

  4. Human onboarding. role_adoption_checklist is surfaced in collaboration sessions so human reviewers know how to assume the persona's role.

  5. Action scoping. inputs and expected_output are matched against the 6 action types (scaffold, refactor, debug, test, compare, document) to determine which actions are applicable.

Persona YAML Format

Persona YAML files live in src/fcc/data/personas/. Each file contains a list of persona definitions under a top-level personas: key. Files are validated against the JSON Schema at src/fcc/data/schemas/persona_schema.json.

The PersonaRegistry.from_yaml_directory() method loads all *.yaml files from a directory, merging them into a single registry. This supports modular persona organization -- core personas in one file, integration personas in another, plugin-contributed personas in a third.

from fcc.personas.registry import PersonaRegistry

# Load all persona YAML files from the data directory
registry = PersonaRegistry.from_yaml_directory("src/fcc/data/personas/")

# Access a specific persona
sqc = registry.get("SQC")
print(sqc.riscear.role)
print(sqc.riscear.archetype)
print(sqc.riscear.constraints)

Key Takeaways

  • R.I.S.C.E.A.R. is a 10-component specification: Role, Inputs, Style, Constraints, Expected Output, Archetype, Responsibilities, Role Skills, Role Collaborators, and Role Adoption Checklist.
  • The specification is implemented as the RISCEARSpec frozen dataclass and serialized to YAML.
  • At runtime, R.I.S.C.E.A.R. fields drive prompt generation, governance enforcement, cross-reference wiring, human onboarding, and action scoping.
  • Persona YAML files are validated against a JSON Schema and loaded by PersonaRegistry.
  • The three extended components (Skills, Collaborators, Adoption Checklist) default to empty lists, preserving backward compatibility with 7-component definitions.

Previous: Chapter 2 -- Object Model Patterns | Next: Chapter 4 -- Persona Dimensions

Try this in Notebook 03