Contributing Cross-References¶

This guide covers how to add, modify, and validate cross-reference entries in the FCC framework. Follow these steps to ensure new entries are consistent, well-described, and pass all quality gates.

How the Cross-Reference Data Model Works¶

The cross-reference matrix lives in a single YAML file:

data/personas/cross_reference.yaml

This file is the authoritative source for persona-to-persona interactions. It is loaded by CrossReferenceMatrix.from_yaml() and consumed by:

The docs-as-code generator (per-persona coordination pages)
The simulation engine (workflow traversal validation)
Quality gate checks (QG-XREF-001, QG-XREF-002, QG-XREF-003)
The CLI fcc validate command

The Python data model consists of two classes:

CrossReferenceEntry: A frozen dataclass with 5 fields (source_id, target_id, relationship_type, interaction, strength)
CrossReferenceMatrix: A queryable container of entries with construction, query, mutation, and serialization methods

Step-by-Step: Adding Entries to cross_reference.yaml¶

1. Identify the Interaction¶

Before adding an entry, answer these questions:

Who initiates? This is the source_id.
Who receives? This is the target_id.
What is exchanged? This becomes the interaction text.
What is the nature of the exchange? This determines the relationship_type.
Is it critical path? This determines the strength.

2. Choose the Correct Group¶

Entries are organized into 5 groups in the YAML file. Add your entry to the appropriate group:

Group	Section Header	When to Use
Group 1	Core Personas	Both source and target are in
Group 2	Integration Specialists	Source or target is in
Group 3	Governance Personas	Source or target is in
Group 4	Stakeholder Hub	Source or target is in
Group 5	Champion Personas	Source or target is in

If the entry spans categories (e.g., core to governance), place it in the group of the source persona.

3. Write the YAML Entry¶

- source_id: XX          # 2-5 uppercase letters
  target_id: YY          # 2-5 uppercase letters
  relationship_type: handoff  # or: feedback, coordination, governance, champion-of
  interaction: "Verb phrase describing what is exchanged"
  strength: primary       # or: secondary

4. Validate the Entry¶

Run schema validation:

fcc validate

Or validate programmatically:

from fcc.personas.cross_reference import CrossReferenceMatrix

matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
print(f"Loaded {len(matrix)} entries successfully")

Relationship Type Selection Guide¶

Use this decision tree to select the correct relationship type:

Does the source persona transfer ownership of a deliverable?
  |
  +-- YES: Does the target persona have authority over the source?
  |     |
  |     +-- NO --> handoff
  |     +-- YES --> Still handoff (governance is for compliance reporting, not artifact transfer)
  |
  +-- NO: Does the source persona report compliance/oversight status?
        |
        +-- YES: Does the target have authority to block progress?
        |     |
        |     +-- YES --> governance
        |     +-- NO --> feedback
        |
        +-- NO: Does the source persona return evaluations/corrections?
              |
              +-- YES --> feedback
              |
              +-- NO: Do both personas share information bidirectionally?
                    |
                    +-- YES --> coordination
                    |
                    +-- NO: Is this a champion elevating its base persona?
                          |
                          +-- YES --> champion-of
                          +-- NO --> Reconsider the interaction -- it may not need an entry

Quick Decision Table¶

Scenario	Type
RC gives inventory to BC	`handoff`
DE sends corrections back to BC	`feedback`
RB and UG cross-link their docs	`coordination`
DGS reports compliance to GCA	`governance`
RCHM declares it elevates RC	`champion-of`

Strength Rating Guidelines¶

When to Use `primary`¶

The target persona cannot do its job without this interaction.
Removing this entry would break the workflow.
The interaction is on the critical path of the FCC cycle.

Examples:

# BC cannot create blueprints without research inventory
- source_id: RC
  target_id: BC
  relationship_type: handoff
  interaction: Delivers research inventory; clarifies context
  strength: primary

# GCA cannot audit without compliance reports
- source_id: DGS
  target_id: GCA
  relationship_type: governance
  interaction: Reports compliance status for governance audit
  strength: primary

When to Use `secondary`¶

The target persona can function without this interaction but produces better results with it.
The interaction provides supplementary context rather than essential input.
Removing this entry would degrade quality but not break the workflow.

Examples:

# RB can work without RC's operational flags, but benefits from them
- source_id: RC
  target_id: RB
  relationship_type: handoff
  interaction: Flags operational scenarios for automation
  strength: secondary

# STE can work without DE coordination, but terminology stays more consistent with it
- source_id: STE
  target_id: DE
  relationship_type: coordination
  interaction: Validates terminology against documentation standards
  strength: secondary

Interaction Description Writing Style Guide¶

The interaction field should be a concise verb phrase that describes what is exchanged and why.

Format¶

[Verb] [object] [for/to purpose]

Good Examples¶

Interaction	Why It Works
`Delivers research inventory; clarifies context`	Verb + object + supplementary action
`Returns standards and edits on blueprints`	Clear reverse flow (feedback)
`Reports compliance status for governance audit`	States what is reported and why
`Aligns index schemas with semantic taxonomy`	Mutual action (coordination)
`Champions and elevates the Research Crafter persona`	Architectural declaration

Avoid¶

Bad Example	Problem	Fix
`Sends stuff to BC`	Vague	`Provides research inventory for blueprint creation`
`Works with DE`	No specifics	`Validates terminology against documentation standards`
`RC does research`	Describes the persona, not the interaction	`Delivers research findings for blueprint context`
`Handoff`	Just restates the type	`Submits blueprints for quality validation`

Rules¶

Start with a verb: Delivers, Provides, Returns, Reports, Aligns, Champions, Orchestrates, Submits, Supplies, Receives, Reviews, Validates, Coordinates, Flags, Compiles.
Name the artifact: research inventory, blueprints, compliance status, taxonomy schemas, user guides.
State the purpose: for blueprint creation, for governance audit, for quality validation, for publishing.
Keep it under 80 characters when possible.
Be specific enough that someone reading only the interaction text understands what flows between the two personas.

Schema Validation Requirements¶

All entries in cross_reference.yaml must conform to the JSON Schema at data/schemas/cross_reference.schema.json:

Field	Constraint
`source_id`	String matching `^[A-Z]{2,5}$`
`target_id`	String matching `^[A-Z]{2,5}$`
`relationship_type`	Enum: `handoff`, `feedback`, `coordination`, `governance`, `champion-of`
`interaction`	Non-empty string (`minLength: 1`)
`strength`	Enum: `primary`, `secondary` (optional, defaults to `primary`)

No additional properties are allowed on entries.

Testing Checklist for New Entries¶

Before submitting a PR with new cross-reference entries:

How to Verify with fcc validate¶

Basic Validation¶

# Validate all data files
fcc validate

# Expected output (no errors):
# Validating data/personas/cross_reference.yaml... OK
# Validating data/personas/core.yaml... OK
# ...

Programmatic Verification¶

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

matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
registry = PersonaRegistry.from_yaml_directory("data/personas/")

# QG-XREF-001: All 24 personas covered
expected_ids = set(registry.ids)
matrix_ids = matrix.all_persona_ids()
assert expected_ids == matrix_ids, f"Missing: {expected_ids - matrix_ids}"

# QG-XREF-002: All 5 types present
found_types = {e.relationship_type for e in matrix}
required_types = {"handoff", "feedback", "coordination", "governance", "champion-of"}
assert required_types == found_types, f"Missing types: {required_types - found_types}"

# QG-XREF-003: No orphan IDs
orphans = matrix_ids - expected_ids
assert not orphans, f"Orphan IDs: {orphans}"

print(f"All quality gates passed: {len(matrix)} entries, {len(matrix_ids)} personas")

Check for Duplicates¶

from collections import Counter

keys = [(e.source_id, e.target_id, e.relationship_type) for e in matrix]
duplicates = [k for k, count in Counter(keys).items() if count > 1]
if duplicates:
    print(f"WARNING: Duplicate keys found: {duplicates}")
else:
    print("No duplicate keys")

Example PR: Adding a New Entry¶

Here is a complete example of adding a new cross-reference entry.

1. Edit the YAML File¶

Add to the appropriate group in data/personas/cross_reference.yaml:

  # (in Group 2: Integration Specialists)

  # STE also provides terminology context for traceability
  - source_id: STE
    target_id: TS
    relationship_type: handoff
    interaction: Provides terminology standards for traceability linking
    strength: secondary

2. Run Validation¶

fcc validate
make test

3. Verify Programmatically¶

matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
new_entries = matrix.between("STE", "TS")
assert len(new_entries) > 0
print(f"New entry verified: {new_entries[0].interaction}")

4. Commit¶

git add data/personas/cross_reference.yaml
git commit -m "Add STE->TS handoff for terminology standards in traceability"

API Reference: Cross-Reference -- Full Python API documentation
Cross-Reference Matrix Specification -- Data model and tables
Interaction Cookbook -- Recipes for common patterns
Contributing Guide -- General contribution guidelines