Skip to content

Cross-Reference Matrix

The cross-reference matrix is the authoritative map of every persona-to-persona interaction in the FCC framework. It captures 106 entries across 24 personas in 5 categories, encoding who talks to whom, what they exchange, and why.

Purpose

FCC personas do not operate in isolation. The Find-Create-Critique cycle depends on structured handoffs, feedback loops, coordination agreements, governance oversight, and champion orchestration. The cross-reference matrix makes these relationships explicit, queryable, and validatable.

Without the matrix, interaction patterns live only in prose descriptions and workflow edge labels. The matrix elevates them to first-class data that can be:

  • Queried programmatically (upstream, downstream, peers, by type)
  • Validated against quality gates (QG-XREF-001, QG-XREF-002, QG-XREF-003)
  • Merged from multiple sources with conflict resolution
  • Generated into documentation via the docs-as-code pipeline

The 5 Relationship Types

Every cross-reference entry has a relationship_type drawn from exactly five values.

handoff

A handoff transfers a completed deliverable from one persona to another. Ownership changes. The source persona has finished its work on the artifact; the target persona picks it up and carries it forward.

Attribute Value
Direction Source to target (unidirectional)
Ownership Transfers from source to target
Example RC -> BC: Delivers research inventory; clarifies context
When to use The receiving persona needs the artifact to begin or continue its own work

feedback

A feedback relationship sends evaluation, corrections, or observations back toward the producing persona. It does not transfer ownership -- it informs the source so it can improve.

Attribute Value
Direction Target back to source (reverse flow)
Ownership Remains with original producer
Example DE -> BC: Returns standards and edits on blueprints
When to use The receiving persona reviews output and returns comments or corrections

coordination

A coordination relationship describes two personas that share information bidirectionally without a clear producer/consumer hierarchy. They align on standards, resolve conflicts, or cross-link artifacts.

Attribute Value
Direction Bidirectional
Ownership Shared or separate
Example RB <-> UG: Cross-links quick fixes and operational steps
When to use Two personas must stay synchronized but neither owns the other's deliverable

governance

A governance relationship represents oversight. The source persona reports compliance status, audit results, or policy conformance to the target (typically GCA or a governance-adjacent persona). Unlike feedback, governance relationships carry authority -- they can block downstream progress.

Attribute Value
Direction Source reports to governance target
Ownership Source retains artifact ownership; target has oversight authority
Example DGS -> GCA: Reports compliance status for governance audit
When to use A persona must demonstrate compliance to a governance authority before proceeding

champion-of

A champion-of relationship links a champion persona to the base persona it elevates. This is distinct from handoff -- it represents an ongoing orchestration relationship, not a one-time transfer. The champion coordinates a team of personas that includes the base persona.

Attribute Value
Direction Champion to base persona
Ownership Champion coordinates; base persona retains deliverable ownership
Example RCHM -> RC: Champions and elevates the Research Crafter persona
When to use Defining the champion architecture -- each champion has exactly one champion-of entry

Strength Ratings

Each entry has a strength field indicating its importance in the workflow.

Strength Meaning Guideline
primary Critical path relationship. Blocking if absent. The target persona cannot do its job without this interaction.
secondary Supporting relationship. Enhances quality but is not blocking. The target persona can function without this but produces better results with it.

Default: If strength is omitted, it defaults to "primary".

Data Model Reference

CrossReferenceEntry

A frozen dataclass representing a single interaction between two personas.

from dataclasses import dataclass

@dataclass(frozen=True)
class CrossReferenceEntry:
    source_id: str          # Persona ID of the sender (e.g., "RC")
    target_id: str          # Persona ID of the receiver (e.g., "BC")
    relationship_type: str  # One of: handoff, feedback, coordination, governance, champion-of
    interaction: str        # Human-readable description of what is exchanged
    strength: str = "primary"  # "primary" or "secondary"

Construction: CrossReferenceEntry.from_dict(data) / Serialization: entry.to_dict()

CrossReferenceMatrix

A queryable container holding a list of CrossReferenceEntry objects.

class CrossReferenceMatrix:
    # Construction
    from_yaml(path)                         # Load from YAML file (authoritative source)
    from_personas(registry)                 # Auto-generate from PersonaRegistry collaboration links
    merge_with_precedence(other)            # Merge two matrices; self takes precedence on key conflicts

    # Queries
    upstream(persona_id)                    # Entries where persona is the target (incoming)
    downstream(persona_id)                  # Entries where persona is the source (outgoing)
    peers(persona_id)                       # Coordination entries involving persona
    by_type(relationship_type)              # All entries of a given type
    between(source_id, target_id)           # Directional entries between two personas
    all_persona_ids()                       # Set of all unique persona IDs in the matrix

    # Mutation
    add(entry)                              # Append a single entry
    merge(other)                            # Combine two matrices (simple concatenation)

    # Serialization
    to_yaml(path)                           # Write to YAML file
    entries                                 # Property: list of all entries
    __len__()                               # Number of entries
    __iter__()                              # Iterate over entries

Full Interaction Matrix

Group 1: Core Personas (22 entries)

Source Target Type Interaction Strength
RC BC handoff Delivers research inventory; clarifies context primary
RC DE handoff Provides annotated references for cross-linking primary
RC RB handoff Flags operational scenarios for automation secondary
RC UG handoff Compiles user pain points for onboarding guides secondary
RC TS handoff Provides requirements for traceability linking primary
BC DE handoff Submits blueprints for review primary
BC RB handoff Provides operational blueprints and updated specs primary
BC UG handoff Provides onboarding scaffolds and updated specs primary
BC BV handoff Submits blueprints for quality validation primary
BC UMC handoff Provides specifications for mockup creation primary
DE RB handoff Publishes and hands off operational docs primary
DE UG handoff Publishes and hands off user-facing docs primary
DE SCP handoff Provides approved documentation for publishing primary
DE UGCH handoff Hands off approved content for publishing orchestration primary
DE BC feedback Returns standards and edits on blueprints primary
RB BC feedback Provides operational feedback on specs primary
RB RC feedback Reports operational findings for knowledge base secondary
UG BC feedback Provides usability feedback on specs primary
UG RC feedback Reports user feedback for knowledge base secondary
UG SCP handoff Provides user guides for multi-channel publishing primary
RB UG coordination Cross-links quick fixes and operational steps primary
UG RB coordination Cross-links quick fixes and recovery steps primary

Group 2: Integration Specialists (28 entries)

Source Target Type Interaction Strength
CIA STE coordination Aligns index schemas with semantic taxonomy primary
CIA RC handoff Provides indexed assets for research curation primary
CIA BC handoff Supplies catalog data for blueprint context primary
CIA GCA handoff Reports coverage gaps for compliance review secondary
STE CIA coordination Aligns taxonomy definitions with catalog index schemas primary
STE RC handoff Provides terminology standards for research consistency primary
STE DGS handoff Supplies classification schemas for governance alignment primary
STE DE coordination Validates terminology against documentation standards secondary
TS RC feedback Receives requirements for traceability linking primary
TS BC feedback Traces blueprint artifacts back to requirements primary
TS BV coordination Validates trace coverage with quality checks primary
TS GCA handoff Reports compliance gaps for governance audit primary
BV BC feedback Returns quality validation results on blueprints primary
BV DE handoff Reports quality issues and standards gaps primary
BV TS coordination Validates trace coverage completeness primary
BV GCA handoff Submits compliance verification results primary
UMC BC feedback Returns visual prototypes aligned to specifications primary
UMC BV handoff Submits mockups for design quality review primary
UMC UG handoff Supplies visual assets for user guide illustrations primary
UMC DE coordination Aligns design patterns with documentation standards secondary
RIC RC coordination Supplements manual research with automated inventories primary
RIC BC handoff Provides structured data for blueprint creation primary
RIC CIA handoff Supplies capability data for catalog indexing primary
RIC TS handoff Reports coverage gaps for traceability tracking secondary
GCA DE feedback Audits documentation for governance compliance primary
GCA BV feedback Receives validation results for compliance review secondary
GCA TS feedback Reviews traceability for compliance completeness secondary
GCA CO handoff Reports governance status for coordination primary

Group 3: Governance Personas (12 entries)

Source Target Type Interaction Strength
DGS BC handoff Provides governance context for blueprint creation primary
DGS STE coordination Aligns data schemas with semantic taxonomy primary
DGS GCA governance Reports compliance status for governance audit primary
DGS PTE handoff Supplies integration data for privacy classification primary
PTE DGS feedback Receives data schemas for classification alignment primary
PTE STE coordination Aligns classification with semantic taxonomy secondary
PTE GCA governance Reports privacy compliance for governance audit primary
PTE AMS handoff Provides classification context for content validation primary
AMS DE feedback Reviews documentation for factual accuracy primary
AMS PTE feedback Receives classification context for sensitive content secondary
AMS GCA governance Reports validation results for governance compliance primary
AMS BC feedback Provides quality feedback on blueprint accuracy primary

Group 4: Stakeholder Hub (20 entries)

Source Target Type Interaction Strength
CO GCA feedback Receives governance status for coordination planning primary
CO EC handoff Provides status updates for executive communication primary
CO RS coordination Aligns timelines and resolves scheduling conflicts primary
CO DE coordination Coordinates documentation handoffs across teams secondary
SMC EC handoff Provides metrics for executive reporting primary
SMC CO feedback Receives coordination data for metrics collection secondary
SMC BV handoff Supplies quality metrics for validation context secondary
SMC RS handoff Reports trends for roadmap planning primary
EC SMC feedback Receives metrics for executive communication primary
EC CO feedback Receives status updates for communication synthesis primary
EC SCP handoff Provides executive packages for publishing primary
EC DE coordination Aligns messaging with documentation standards secondary
RS CO coordination Aligns timelines and resolves scheduling conflicts primary
RS SMC feedback Receives trend data for planning adjustments secondary
RS EC handoff Provides roadmap data for executive communication primary
RS RC coordination Coordinates research milestones with project timeline secondary
SCP EC feedback Receives executive packages for multi-channel publishing primary
SCP DE feedback Publishes approved documentation to target audiences primary
SCP UG feedback Distributes user guides to target audiences secondary
SCP CO handoff Reports distribution metrics for coordination review primary

Group 5: Champion Personas (24 entries)

Source Target Type Interaction Strength
RCHM RC champion-of Champions and elevates the Research Crafter persona primary
RCHM RC handoff Orchestrates core research activities primary
RCHM CIA handoff Orchestrates catalog indexing activities primary
RCHM STE handoff Orchestrates taxonomy engineering activities primary
RCHM RIC handoff Orchestrates research automation activities primary
RCHM BCHM handoff Hands off unified research package to Create phase primary
BCHM BC champion-of Champions and elevates the Blueprint Crafter persona primary
BCHM BC handoff Orchestrates core blueprint creation primary
BCHM BV handoff Orchestrates quality validation primary
BCHM UMC handoff Orchestrates mockup creation and integration primary
BCHM RIC handoff Orchestrates research data integration secondary
BCHM RCHM feedback Receives unified research packages primary
BCHM DE handoff Hands off blueprint packages for critique primary
BCHM RBCH handoff Hands off blueprints for operational implementation primary
UGCH UG champion-of Champions and elevates the User Guide Crafter persona primary
UGCH UG handoff Orchestrates user guide creation primary
UGCH SCP handoff Orchestrates multi-channel publishing primary
UGCH EC handoff Orchestrates executive communications primary
UGCH DE feedback Receives approved documentation for publishing primary
RBCH RB champion-of Champions and elevates the Runbook Crafter persona primary
RBCH RB handoff Orchestrates runbook creation and updates primary
RBCH GCA handoff Orchestrates compliance auditing primary
RBCH TS handoff Orchestrates traceability verification primary
RBCH BCHM feedback Receives blueprints for operational implementation primary

Category Interaction Diagram

The following diagram shows how relationship types flow between the five persona categories.

graph TB
    subgraph Find
        RC[RC]
        CIA[CIA]
        STE[STE]
        RIC[RIC]
    end

    subgraph Create
        BC[BC]
        BV[BV]
        UMC[UMC]
        TS[TS]
    end

    subgraph Critique
        DE[DE]
    end

    subgraph Governance
        DGS[DGS]
        PTE[PTE]
        AMS[AMS]
        GCA[GCA]
    end

    subgraph Stakeholder
        CO[CO]
        SMC[SMC]
        EC[EC]
        RS[RS]
        SCP[SCP]
    end

    subgraph Champions
        RCHM[RCHM]
        BCHM[BCHM]
        UGCH[UGCH]
        RBCH[RBCH]
    end

    RCHM -->|champion-of| RC
    BCHM -->|champion-of| BC
    UGCH -->|champion-of| UG
    RBCH -->|champion-of| RB

    RC -->|handoff| BC
    BC -->|handoff| DE
    DE -->|feedback| BC

    DGS -->|governance| GCA
    PTE -->|governance| GCA
    AMS -->|governance| GCA

    GCA -->|handoff| CO
    CO -->|handoff| EC
    EC -->|handoff| SCP

    RCHM -->|handoff| BCHM
    BCHM -->|handoff| RBCH
    DE -->|handoff| UGCH

    RB ---|coordination| UG

    style Find fill:#E3F2FD,stroke:#1565C0
    style Create fill:#E8F5E9,stroke:#2E7D32
    style Critique fill:#FFF3E0,stroke:#EF6C00
    style Governance fill:#FCE4EC,stroke:#C62828
    style Stakeholder fill:#F3E5F5,stroke:#6A1B9A
    style Champions fill:#FFF8E1,stroke:#F9A825

Inter-Category Flow Summary

graph LR
    C[Champions] -->|orchestrate| F[Find]
    C -->|orchestrate| Cr[Create]
    C -->|orchestrate| Cq[Critique]
    C -->|orchestrate| S[Stakeholder]
    F -->|handoff| Cr
    Cr -->|handoff| Cq
    Cq -->|feedback| Cr
    F -->|handoff| Cr
    G[Governance] -->|governance| G
    G -->|feedback| Cq
    G -->|handoff| S
    S -->|coordination| S
    Cq -->|handoff| S

Source Architecture

The cross-reference matrix has two data sources, with a clear precedence model.

YAML: Authoritative Source

The file data/personas/cross_reference.yaml is the single source of truth. It contains all 106 hand-authored entries with curated interaction descriptions and strength ratings.

from fcc.personas.cross_reference import CrossReferenceMatrix

matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
print(len(matrix))  # 106

from_personas(): Supplementary Source

CrossReferenceMatrix.from_personas(registry) auto-generates entries from the collaboration field on each PersonaSpec. This is useful for bootstrapping but produces less descriptive interaction text and defaults all strengths to "primary".

from fcc.personas.registry import PersonaRegistry
from fcc.personas.cross_reference import CrossReferenceMatrix

registry = PersonaRegistry.from_yaml_directory("data/personas/")
auto_matrix = CrossReferenceMatrix.from_personas(registry)

merge_with_precedence(): Conflict Resolution

When combining YAML and auto-generated entries, use merge_with_precedence(). The calling matrix takes precedence on key conflicts. Keys are (source_id, target_id, relationship_type).

yaml_matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
auto_matrix = CrossReferenceMatrix.from_personas(registry)

# YAML entries win on conflicts; auto-generated entries fill gaps
combined = yaml_matrix.merge_with_precedence(auto_matrix)

This pattern ensures that hand-authored interaction descriptions and strength ratings are always preferred over auto-generated defaults.