Cross-Reference Matrix Video Script¶

A structured script outline for a 15-minute walkthrough video covering the FCC cross-reference matrix. Target audience: developers and technical leads adopting FCC for the first time.

Act 1: What Is the Cross-Reference Matrix? (2 minutes)¶

Narration¶

"The FCC framework has 24 personas across 5 categories. But personas do not work in isolation -- they exchange deliverables, provide feedback, coordinate standards, report compliance, and orchestrate teams. The cross-reference matrix is the authoritative map of every one of these 106 interactions."

Visual: Opening Slide¶

Title: "FCC Cross-Reference Matrix: 24 Personas, 106 Interactions"
Subtitle: "The interaction map that makes FCC workflows auditable, queryable, and extensible"

Visual: Before/After Comparison¶

Before the matrix: Show a tangled web of arrows between persona icons with no labels or structure. Caption: "Implicit interactions -- hard to trace, impossible to validate."

After the matrix: Show the same personas with clean, labeled arrows grouped by type. Caption: "106 structured entries -- queryable, validatable, and docs-as-code ready."

Key Points¶

The matrix is a YAML file: data/personas/cross_reference.yaml
Each entry has 5 fields: source_id, target_id, relationship_type, interaction, strength
The matrix is loaded by CrossReferenceMatrix.from_yaml() and queried with Python methods

Storyboard Note¶

Animate the 5 fields appearing one by one next to a sample YAML entry. Highlight each field with a colored box as it is explained.

Act 2: The 5 Relationship Types (3 minutes)¶

Narration¶

"Every interaction in FCC is one of exactly five types. Understanding these types is the key to reading and extending the matrix."

Visual: Type Cards¶

Show five cards, each with a colored icon, that flip to reveal the definition:

handoff (blue arrow) -- "Transfer a deliverable. Ownership changes."
feedback (orange reverse arrow) -- "Return evaluations. Ownership stays."
coordination (green double arrow) -- "Bidirectional alignment. No ownership transfer."
governance (red shield) -- "Report compliance. Authority to block."
champion-of (gold star) -- "Elevate a base persona. Ongoing orchestration."

Visual: Decision Flowchart¶

Animate the relationship type decision tree:

Does ownership transfer?
  YES --> handoff
  NO --> Does the target have oversight authority?
    YES --> governance
    NO --> Is it an evaluation/correction return?
      YES --> feedback
      NO --> Is it bidirectional alignment?
        YES --> coordination
        NO --> Is it a champion elevating a base persona?
          YES --> champion-of

Example for Each Type¶

Type	Visual	Example
handoff	RC icon slides a document to BC icon	"RC delivers research inventory to BC"
feedback	DE icon returns a red-pen document to BC icon	"DE returns standards edits on blueprints"
coordination	RB and UG icons exchange documents simultaneously	"RB and UG cross-link operational steps"
governance	DGS icon presents a report to GCA shield icon	"DGS reports compliance to GCA"
champion-of	RCHM gold icon hovers above RC icon	"RCHM champions the Research Crafter"

Storyboard Note¶

Use consistent color coding throughout the video: blue for handoff, orange for feedback, green for coordination, red for governance, gold for champion-of. These colors should appear on arrows, cards, and code highlights.

Act 3: The 24-Persona Interaction Map (5 minutes)¶

Narration¶

"Let's walk through the full matrix. We'll start with the core 5 personas, add the 7 integration specialists, layer in governance, connect stakeholders, and finally show how the 4 champions orchestrate it all."

Visual: Layered Build-Up¶

Build the diagram in 5 stages, adding one category at a time.

Stage 1: Core (5 personas, ~22 entries)¶

graph LR
    RC -->|handoff| BC
    BC -->|handoff| DE
    DE -->|feedback| BC
    BC -->|handoff| RB
    BC -->|handoff| UG
    DE -->|handoff| RB
    DE -->|handoff| UG
    RB -->|feedback| BC
    UG -->|feedback| BC
    RB ---|coordination| UG

Narration: "The core 5 form the backbone. RC finds, BC creates, DE critiques. RB and UG receive blueprints and provide feedback. RB and UG coordinate their operational and user-facing docs."

Stage 2: Add Integration (7 personas, +28 entries)¶

Highlight new personas appearing around the core: - CIA and STE coordinate on taxonomy (green arrows) - TS and BV provide quality feedback to BC (orange arrows) - UMC receives specs from BC and sends mockups back (blue and orange) - RIC supplies data to multiple personas (blue arrows) - GCA collects compliance data from TS and BV (blue arrows)

Narration: "Integration specialists fill in the gaps. They handle indexing, taxonomy, traceability, validation, mockups, research automation, and compliance auditing."

Stage 3: Add Governance (3 personas, +12 entries)¶

DGS, PTE, and AMS appear with red governance arrows to GCA.

Narration: "Governance personas report to GCA through governance-type relationships. This is oversight with authority -- GCA can block progress if compliance is not met."

Stage 4: Add Stakeholder (5 personas, +20 entries)¶

CO, SMC, EC, RS, SCP appear in a hub pattern.

Narration: "Stakeholders form a hub. CO orchestrates coordination, SMC tracks metrics, EC communicates to executives, RS synchronizes roadmaps, and SCP publishes across channels."

Stage 5: Add Champions (4 personas, +24 entries)¶

RCHM, BCHM, UGCH, RBCH appear with gold champion-of arrows.

Narration: "Champions sit above the workflow, orchestrating teams of personas into unified deliverable packages. They hand off to each other: RCHM to BCHM, BCHM to RBCH, and DE bridges to UGCH."

Visual: Final Assembled Diagram¶

Show the complete 24-persona diagram with all 106 entries. Color-code by relationship type. Zoom into different sections as the narrator highlights key patterns.

Storyboard Note¶

Each stage should take approximately 1 minute. Use smooth animations to show new personas and arrows appearing. Consider a split-screen with the diagram on the left and a scrolling YAML view on the right showing the corresponding entries.

Act 4: Querying the Matrix in Python (3 minutes)¶

Narration¶

"The matrix is not just documentation -- it is queryable data. Let's load it and run some real queries."

Visual: Live Code Demo¶

Show a terminal/IDE with Python code being typed and executed.

Demo 1: Load and Inspect¶

from fcc.personas.cross_reference import CrossReferenceMatrix

matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
print(f"Entries: {len(matrix)}")        # 106
print(f"Personas: {len(matrix.all_persona_ids())}")  # 24

Narration: "Two lines to load, two lines to inspect. 106 entries, 24 personas."

Demo 2: Upstream/Downstream¶

# Who sends work to BC?
for e in matrix.upstream("BC"):
    print(f"  {e.source_id} [{e.relationship_type}]: {e.interaction}")

Narration: "upstream() shows everything flowing into a persona. BC receives handoffs from RC, CIA, RIC, DGS, plus feedback from DE, RB, UG, BV, UMC, and AMS."

Demo 3: Trace an Impact Chain¶

def trace_impact(matrix, start_id, visited=None):
    if visited is None:
        visited = set()
    if start_id in visited:
        return visited
    visited.add(start_id)
    for entry in matrix.downstream(start_id):
        if entry.relationship_type in ("handoff", "champion-of"):
            trace_impact(matrix, entry.target_id, visited)
    return visited

affected = trace_impact(matrix, "RC")
print(f"Change in RC affects: {sorted(affected)}")

Narration: "A recursive trace shows that a change in RC cascades to 10 personas. This is the kind of impact analysis that is impossible without structured interaction data."

Storyboard Note¶

Use a dark-themed terminal with syntax highlighting. Show the output appearing line by line after each code block is executed. Consider a picture-in-picture showing the diagram with affected personas lighting up as the trace runs.

Act 5: Adding Custom Entries and Validating (2 minutes)¶

Narration¶

"The matrix is extensible. When you add a persona, you add cross-reference entries to connect it. Then you validate."

Visual: YAML Editing¶

Show cross_reference.yaml in an editor with a new entry being typed:

- source_id: APT
  target_id: BV
  relationship_type: handoff
  interaction: Submits API test results for quality validation
  strength: primary

Visual: Validation¶

$ fcc validate
Validating data/personas/cross_reference.yaml... OK
All quality gates passed.

Visual: Quality Gate Check¶

Show the three quality gates as a checklist that fills with green checkmarks:

QG-XREF-001: Coverage -- All personas represented
QG-XREF-002: Type Completeness -- All 5 types used
QG-XREF-003: Workflow Alignment -- No orphan IDs

Narration¶

"Three quality gates protect the matrix. Coverage ensures every persona is connected. Type completeness ensures all five relationship types are used. Workflow alignment ensures the matrix and workflow graph stay synchronized."

Storyboard Note¶

End with a final wide shot of the complete 24-persona diagram with the new APT persona highlighted. Zoom out to show the full FCC ecosystem.

Visual Production Notes¶

Color Palette¶

Element	Color	Hex
handoff arrows	Blue	`#1565C0`
feedback arrows	Orange	`#EF6C00`
coordination arrows	Green	`#2E7D32`
governance arrows	Red	`#C62828`
champion-of arrows	Gold	`#F9A825`
Core category	Light blue background	`#E3F2FD`
Integration category	Light green background	`#E8F5E9`
Governance category	Light pink background	`#FCE4EC`
Stakeholder category	Light purple background	`#F3E5F5`
Champion category	Light yellow background	`#FFF8E1`

Typography¶

Headings: Sans-serif, bold
Code: Monospace (JetBrains Mono or similar)
YAML entries: Monospace with syntax highlighting

Narration Tone¶

Professional but accessible. Avoid jargon where possible; define terms on first use.
Paced for comprehension. Each concept gets 15-30 seconds before moving on.
Active voice throughout. "The matrix contains 106 entries" not "106 entries are contained in the matrix."
Assume the viewer is technical but new to FCC. Do not assume knowledge of persona IDs or relationship types.

Audience Targeting¶

Audience	What They Get from This Video
Developers adopting FCC	Understand how to query and extend the matrix in code
Technical leads	See the governance and compliance layer
Project managers	Understand the interaction map at a high level (Acts 1-3)
Contributors	Learn how to add entries and pass validation (Act 5)

Recommended Screen Resolution¶

Record at 1920x1080
Terminal font size: 16pt minimum
Diagram zoom level: Personas readable without squinting

Timing Summary¶

Act	Duration	Content
1	2 min	What and why
2	3 min	5 relationship types
3	5 min	24-persona walkthrough
4	3 min	Python querying
5	2 min	Adding and validating
Total	15 min

Cross-Reference Matrix Specification -- Source material for Act 1 and 3
API Reference -- Source material for Act 4
Contributing Cross-References -- Source material for Act 5
Interaction Cookbook -- Extended code examples

Cross-Reference Matrix Video Script¶

Act 1: What Is the Cross-Reference Matrix? (2 minutes)¶

Narration¶

Visual: Opening Slide¶

Visual: Before/After Comparison¶

Key Points¶

Storyboard Note¶

Act 2: The 5 Relationship Types (3 minutes)¶

Narration¶

Visual: Type Cards¶

Visual: Decision Flowchart¶

Example for Each Type¶

Storyboard Note¶

Act 3: The 24-Persona Interaction Map (5 minutes)¶

Narration¶

Visual: Layered Build-Up¶

Stage 1: Core (5 personas, ~22 entries)¶

Stage 2: Add Integration (7 personas, +28 entries)¶

Stage 3: Add Governance (3 personas, +12 entries)¶

Stage 4: Add Stakeholder (5 personas, +20 entries)¶

Stage 5: Add Champions (4 personas, +24 entries)¶

Visual: Final Assembled Diagram¶

Storyboard Note¶

Act 4: Querying the Matrix in Python (3 minutes)¶

Narration¶

Visual: Live Code Demo¶

Demo 1: Load and Inspect¶

Demo 2: Upstream/Downstream¶

Demo 3: Trace an Impact Chain¶

Storyboard Note¶

Act 5: Adding Custom Entries and Validating (2 minutes)¶

Narration¶

Visual: YAML Editing¶

Visual: Validation¶

Visual: Quality Gate Check¶

Narration¶

Storyboard Note¶

Visual Production Notes¶

Color Palette¶

Typography¶

Narration Tone¶

Audience Targeting¶

Recommended Screen Resolution¶

Timing Summary¶

Related Pages¶