Skip to content

Decision Archaeology

When a stakeholder — internal or external, curious or adversarial — asks "why did we decide X in v1.3.5?" or "why does FCC own R.I.S.C.E.A.R. rather than PAOM?", someone has to reconstruct the answer from first principles. The Decision Archaeologist (DAR) persona, introduced in v1.5.0 stage 5, is that someone. DAR is the ecosystem-scale complement to ice_ext's History-Narrator (HNAR): where HNAR narrates history within a single model evolution, DAR reconstructs the strategic WHY across releases, ADRs, and cross-repo decisions.

This page is the auditor-facing reference for DAR. It covers the persona's Zachman cell, the triangulation discipline that grounds every rationale assertion, the ADR-gap finding taxonomy, the artifact bundle pattern used for auditor reviews, and the integration with the ADR-006 through ADR-013 suite shipped in v1.5.1.

The DAR persona, in one paragraph

DAR sits in the EXECUTIVE/WHY cell of the Zachman matrix — the executive row (strategic rationale), the WHY column (motivation). The persona's core output is a rationale reconstruction report: a document that explains, in plain language, why a particular decision was made, with every assertion backed by at least three source references. The three sources are drawn from (1) the ADR archive under docs/decisions/, (2) ModelHistoryEvent streams on the FCC event bus, and (3) git commit or PR history across the ecosystem repos. This ADR → event-stream → commit-cite triangulation is the signature pattern of the persona; a DAR report without three sources is, by the persona's own constraints, not a valid DAR report.

For the full R.I.S.C.E.A.R. specification, see src/fcc/data/personas/decision_archaeologist.yaml.

Why "archaeology"?

The archetype is The Archaeologist. The metaphor is deliberate. An archaeologist does not invent history — they recover it from fragmentary evidence in the ground. A decision archaeologist does not invent rationale — they recover it from fragmentary evidence in the ADR archive, the event stream, and the commit log. Speculation without sourcing is, in both fields, the cardinal sin.

That discipline is what makes DAR useful for audit. When an auditor asks "why?", they get an answer cited to three independent source documents they can read themselves, not a just-so narrative.

The ADR suite DAR operates on (v1.5.1)

v1.5.1 shipped eight new ADRs, completing the documented rationale backfill for the v1.4.1 through v1.5.0 architectural arc. DAR cites these ADRs routinely; auditors benefit from knowing them by name.

ADR Subject Stage of rationale
ADR-006 Dual-bus event architecture PAOMBus + UXBus lane split
ADR-007 SAFe alignment skeleton ART structure, PI calendar
ADR-008 POLARIS absorption ice_ext STATUS.md §1–§5 closures
ADR-009 Universal services coordination 22-entry service superset
ADR-010 Six pillars architecture v1.5.0 pillar A–F
ADR-011 GraphRAG + Zachman filtering Pillar B core choice
ADR-012 CRDT multi-user collaboration Pillar D, y-py + in-memory backends
ADR-013 Bidirectional federation conflict policy Pillar C, cross-namespace resolution

Plus the pre-existing ADR-001 through ADR-005. An auditor running a DAR review should expect every reconstruction report to cite at least one ADR from this list (often more).

The ADR archive at docs/decisions/ is, in DAR's terms, the authoritative source. DAR cannot assert rationale that contradicts an ADR without surfacing the conflict explicitly. When sources conflict, DAR surfaces the conflict rather than resolving it — conflict resolution defers to GCA (Governance Compliance Auditor) and KGSE (Knowledge-Graph Serializer Elevator).

The ModelHistoryEvent stream

FCC's event bus emits ModelHistoryEvent instances whenever the persona/workflow/scenario model changes shape. Each event carries at least:

  • timestamp — Unix epoch seconds with millisecond precision.
  • event_type — enumerated on the event bus (81+ types as of v1.5.0).
  • source — the subsystem that raised the event.
  • payload — structured, JSON-serializable change description.
  • correlation_id — ties the event to a specific run, scenario, or session.

DAR walks the stream chronologically when reconstructing rationale. A typical walk sequence is:

  1. Start at the timestamp of the decision-under-review.
  2. Wind back until the most recent ADR was filed.
  3. Collect all ModelHistoryEvent instances in that window.
  4. Group by source and event_type.
  5. Cross-reference with the commit log for the same window.
  6. Triangulate.

The stream is persisted by the collaboration recorder at src/fcc/collaboration/recording.py; historical streams are available under docs/open-science/events/ and on demand from the observability exporters.

Commit-message and CHANGELOG mining

Commit messages in the FCC ecosystem follow a conventional-commits pattern. DAR exploits this structure to find rationale fast.

# Every commit that references an ADR.
git log --all --oneline --grep="ADR-"

# Every commit that closes a STATUS.md ask.
git log --all --oneline --grep="closes §[0-9]"

# Every commit on a specific persona or subsystem.
git log --all --oneline -- src/fcc/collaboration/

# Every release tag between two versions.
git log v1.4.1..v1.5.0 --oneline

# Every commit that introduced a new persona YAML.
git log --all --oneline --diff-filter=A -- 'src/fcc/data/personas/*.yaml'

CHANGELOG entries are the executive summary. Each ## [1.5.X] section maps roughly to one PI; the Added / Changed / Fixed / Generated subsections line up with the ADR-006 through ADR-013 rationale groups. An auditor can reconstruct the shape of a release in under a minute by reading the CHANGELOG section for that version.

The artifact bundle pattern

When an auditor commissions a DAR rationale review, the deliverable is an artifact bundle: a self-contained directory with every cited source document plus the DAR report itself. The bundle pattern is:

bundle/
├── report.md                  # DAR's narrative, with in-line citations
├── adrs/                      # all cited ADRs (copied, not linked)
├── events/                    # filtered event stream (JSON)
├── commits/                   # git log output for the window
├── changelog-excerpt.md       # relevant CHANGELOG section
├── status-asks/               # relevant STATUS.md §n asks
└── manifest.json              # SHA-256 of every other file + timestamps

manifest.json is the integrity anchor — every subsequent access to the bundle verifies against the manifest. The pattern is borrowed from LTAS's archive manifest discipline (see Long-Term Archive Stewardship) and is deliberate. DAR's rationale reports must survive audit years after the fact; the manifest guarantees that what you read today is bit- identical to what was reviewed at the time.

Interpreting findings

DAR produces four finding types:

adr_gap

A decision was made but no ADR was filed. This is the most common DAR finding. Severity is usually tier_2 (compliance / risk) unless the decision was a breaking API change, in which case it escalates to tier_1 (release-blocking).

Remediation: file a retrospective ADR, reference the decision timestamp + commit + stakeholder discussion. DAR does not author the ADR — that is the owning persona's responsibility. DAR only surfaces the gap.

rationale_conflict

Two or more sources contradict each other on the same decision. Severity is always tier_2. The finding is escalated to GCA for resolution.

Remediation: convene the owning personas, reconcile the sources, and amend either the ADR or the event-stream annotation to remove the conflict.

stale_rationale

A previously valid rationale has been overtaken by events — typically a subsequent ADR supersedes it, or the subsystem it describes has been retired. Severity is tier_3 (improvement).

Remediation: mark the superseded ADR with a superseded-by link to the new ADR. DAR then re-runs the triangulation against the new anchor.

triangulation_incomplete

DAR found fewer than three independent source references for a requested rationale. The assertion is not made — DAR refuses to assert without three sources. Severity is informational; the auditor reads the missing- sources report and decides whether to commission additional evidence collection.

Remediation: expand the evidence base (often via event-stream archaeology in the observability exporters) or accept the gap and record it.

Worked example — auditing "Why does FCC own R.I.S.C.E.A.R.?"

This is a real stakeholder question that DAR has been asked more than once. The triangulation proceeds as follows.

Step 1: Identify the decision window. R.I.S.C.E.A.R. appears in the original persona schema committed in the founding commit of the repo. The window is "project genesis through v1.0.0".

Step 2: Find the ADR. No founding-era ADR exists — the docs/decisions/ tree started with ADR-001 (book series structure) which is post-genesis. DAR flags this as an adr_gap finding of medium severity and notes that strategic ownership was implicit.

Step 3: Find the event-stream anchor. The earliest ModelHistoryEvent for R.I.S.C.E.A.R. schema changes dates from the v1.0.0 release window. The event stream records the 10-element structure and the cross-reference pattern that PAOM subsequently consumed.

Step 4: Find the commit-history anchor. The founding commit carries the original 5-element schema that grew into R.I.S.C.E.A.R. across the next four minor releases. Commit messages from v0.9 through v1.0 show the elements landing one at a time.

Step 5: Triangulate against STATUS.md asks. PAOM's STATUS.md §1 through §4 (across PAOM releases) consistently cite FCC as the canonical R.I.S.C.E.A.R. authority. The third independent source is obtained.

Step 6: Write the report. Three sources: (a) the founding-era event stream, (b) the v1.0.0 commit series, (c) PAOM STATUS.md §1 citations. The report documents the implicit strategic ownership and files an adr_gap finding recommending a retrospective ADR-000 codifying the ownership.

This is a real DAR workflow. It also illustrates why DAR's humility self-rating is 4.5 — when the evidence is thin, DAR surfaces the thinness rather than fabricating rationale.

Integration with the HNAR (ice_ext) narrator

DAR and HNAR (History Narrator, ice_ext) operate at different scales. HNAR walks the history of a single model evolution within ice_ext; DAR walks the history of decisions across the whole ecosystem. They share a narrative protocol — the triangulation discipline — but their data sources differ.

For auditors reviewing a cross-scale question (e.g., "why did this specific model evolution in ice_ext result in a framework-level ADR in FCC?"), the review pattern is:

  1. Commission an HNAR narrative for the ice_ext side.
  2. Commission a DAR narrative for the FCC side.
  3. Cross-check that the two narratives align at the hand-off point.
  4. File a narrative_misalignment finding if they don't.

The ice_ext absorption documented in ADR-008 is the canonical worked example of this cross-scale review pattern.

Per-PI decision-archaeology digest

At the close of each SAFe Program Increment (PI), DAR publishes a decision-archaeology digest for SMC (SAFe Metrics Crafter) scorecards. The digest summarises:

  • Every decision made during the PI and its triangulation status.
  • Every ADR filed during the PI.
  • Every adr_gap finding opened.
  • Every rationale_conflict finding opened and its resolution status.

The digest is the backbone of the PI-level retrospective on rationale discipline. Auditors entering mid-PI can pull the most recent digest and use it as the rationale inventory for the engagement.

What DAR does NOT do

  • DAR does NOT author new ADRs. That is the owning persona's responsibility.
  • DAR does NOT resolve rationale_conflict findings. That is GCA.
  • DAR does NOT make forward-looking strategic decisions. That is the owner + stakeholders.
  • DAR does NOT rewrite event-stream history. The event stream is immutable; DAR is a reader only.

Conflating these is the most common mistake in first-time DAR audits. Keep the lane tight.

Persona Direction Interaction
KGSE downstream Receives rationale-reconstruction evidence for promotion decisions
LTAS upstream Provides archive-manifest provenance for pre-v1.0 decision reconstruction
FA downstream Receives ADR-gap findings during forensic audits
GCA downstream Receives rationale-conflict findings for resolution
SMC downstream Receives per-PI digest for SAFe scorecards

Next steps

  • Read the Advanced Patent Tracking page — PCT and DAR reinforce each other; PCT's matrix rows cite the ADRs DAR reconstructs.
  • Walk the R.I.S.C.E.A.R. Completeness page for the fcc audit personas --strict view of the DAR YAML.
  • Read ADR-006 through ADR-013 — DAR cites all eight routinely.
  • Consult the Codename Decoder for ice_ext, PHOENIX, and NEXUS origin reasoning.
  • Open the DAR persona YAML at src/fcc/data/personas/decision_archaeologist.yaml for the authoritative R.I.S.C.E.A.R. spec.
  • Review docs/personas/evolution/dar.md for the DAR evolution guide (career milestones, first 90 days).
  • Skim docs/tutorials/sample-prompts/persona-dar-prompts.md for ready- to-run rationale-reconstruction prompts.
  • Browse docs/tutorials/advanced-capabilities/bidirectional-federation-patterns.md (Pool B) for the federation context DAR often reconstructs.