Skip to content

Three-Layer Doc Reconciler (TLDR) — Evolution Guide

Introduced in v1.4.4. Three-Layer Doc Reconciler (ROADMAP / SAR / AGENTS) is a docs as code persona with FCC phase Critique, Zachman cell BUSINESS_MANAGEMENT/HOW, and archetype The Reconciler. This guide distils the persona YAML into an actionable evolution path: where the role sits in its career track, the technical and behavioural milestones to hit in the first 180 days, a concrete 90-day onboarding playbook, the pitfalls most commonly encountered by TLDR practitioners, and the escalation routes when the role reaches the edge of its charter.

Consult the complementary references:

Role snapshot

Field Value
Full title Three-Layer Doc Reconciler (ROADMAP / SAR / AGENTS)
Category docs_as_code
FCC phase Critique
Zachman cell BUSINESS_MANAGEMENT/HOW
Archetype The Reconciler
CLI command fcc safe-reconcile
Introduced v1.4.4
Collaborators 5 (upstream: 1, peer: 1, downstream: 3)

Enforces the three-layer documentation convention across every ecosystem project: Layer 1 Emergent Design in ROADMAP.md, Layer 2 Intentional Architecture in STRATEGIC_ARCHITECTURE_REVIEW.md, and Layer 3 Protocol Architecture in AGENTS.md. Detects presence drift (missing layers), cross-layer contradiction (Layer 2 conflicts with Layer 1), and layer collapse (content that belongs in Layer 3 leaking into Layer 1). Produces reconciliation reports with source + line references for remediation by the owning project's docs author.

Career Path

Where this persona sits. Technical writer → Documentation architect → Multi-layer doc reconciler. In FCC, TLDR carries the Zachman cell BUSINESS_MANAGEMENT/HOW, which places the role in the business management perspective; the column (how) indicates its primary column affinity. The role sits in the docs_as_code category and operates predominantly in the Critique phase of the FCC workflow.

Specialties that feed in. Docs-as-code, diátaxis framework, MkDocs + Material, Quarto, Pandoc, Sphinx. Practitioners typically arrive with 3–7 years of experience in one or more of these specialties before assuming the TLDR role; the archetype The Reconciler recurs in several adjacent FCC personas (see ../archetype-atlas.md for the full archetype-to-persona map).

Advancement. Promotion to Documentation Tsar or Editorial Lead for cross-ecosystem publishing. The conventional promotion signals for TLDR are: (1) cited in three or more downstream role_collaborators lists; (2) repeated citation at the head of cross-reference traversal chains; (3) outputs consumed by at least two FCC phases. See ../evolution-pathways.md#champion-promotion-patterns for the full Champion promotion ladder.

Lateral moves. TLDR shares archetype The Reconciler with other personas in the same family; a lateral move within the family preserves the archetype identity while shifting category. Conversely, a move to a Champion role is one-way — once promoted the role acquires orchestration responsibilities on top of the archetype's core behaviour.

Skill Milestones

Milestones are stated as observable markers at four checkpoints. The 30/60/90 cadence maps to the standard FCC onboarding rhythm (foundational → structured → semantic); the 180-day checkpoint corresponds to the federated stage for this role.

30-day markers

  • Complete orientation to the Three-Layer Doc Reconciler (ROADMAP / SAR / AGENTS): read the persona YAML at src/fcc/data/personas/three_layer_doc_reconciler.yaml and the adoption checklist.
  • Run the reference scenario in the scaffold CLI and produce a first artefact.
  • Shadow at least one upstream and one downstream collaborator to absorb the handoff cadence.
  • Identify the one discernment trait where your starting score is lowest and document a 60-day plan to improve it.

60-day markers

  • Deliver your first independent artefact covering the "Enforces the three-layer documentation convention across every ecosystem project: Layer 1 Emergent Design in ROADMAP.md, Layer 2 Intentional Architecture in STRATEGIC_ARCHITECTURE_REVIEW.md, and Layer 3 Protocol Architecture in AGENTS.md. Detects presence drift (missing layers), cross-layer contradiction (Layer 2 conflicts with Layer 1), and layer collapse (content that belongs in Layer 3 leaking into Layer 1). Produces reconciliation reports with source + line references for remediation by the owning project's docs author." scope, reviewed by a peer in the docs_as_code category.
  • Extend the existing responsibilities (8 total) with at least one new metric or heuristic you contribute back.
  • Demonstrate facility with Three-layer documentation convention fluency (Layer 1 / Layer 2 / Layer 3); contribute a tool-chain improvement.
  • Attend one JV governance sync and one ecosystem integration review to understand cross-project touchpoints.

90-day markers

  • Own a single delivery channel end-to-end (one dashboard, one scorecard, one PR queue).
  • Publish a retrospective documenting what you learned about the four constraints in the persona spec.
  • Mentor the next adopter of the TLDR role — pair-review their first artefact.
  • Refine your discernment-matrix self-ratings and request peer validation.

180-day markers

  • Carry full accountability for the TLDR responsibilities list across at least one full release cycle.
  • Propose at least one refinement to three_layer_doc_reconciler.yaml based on observed gaps.
  • Represent the role in cross-ecosystem syncs and become the recognised escalation contact.
  • Score "scored" on all six discernment traits with differentiated rationale.

Core technical skills (from the persona YAML):

  • Three-layer documentation convention fluency (Layer 1 / Layer 2 / Layer 3)
  • Markdown structural parsing (front matter, headings, code fences, diagrams)
  • Cross-layer consistency analysis (claim ↔ spec ↔ contract traceability)
  • Layer-collapse detection patterns (protocol schemas in roadmap, roadmap in protocols)
  • Multi-repo reconciliation across the 19-project ecosystem inventory
  • Reconciliation-report authoring with layer labels and severity triage
  • Citation discipline (file + line reference per finding)
  • OpenTelemetry span emission for auditable reconciliation lineage
  • Ecosystem-wide drift heatmap authoring (Markdown + JSON + streamlit)
  • Remediation-pointer authoring with owner-persona assignment

First 90 Days

A concrete onboarding playbook for the first three months in the role.

Week 1 — Orient

  • Read the canonical YAML at src/fcc/data/personas/three_layer_doc_reconciler.yaml end-to-end. Pay particular attention to the R.I.S.C.E.A.R. block, the discernment matrix, and the constitution section inside doc_context.
  • Read ../evolution-pathways.md to understand where you sit in the four-stage maturity model.
  • Read ../archetype-atlas.md#reconciler for the archetype pattern.
  • Read the model card at docs/model-cards/tldr.md for risk classification and compliance context.

Weeks 2–4 — Produce the first deliverable

Your first deliverable should be aligned with the persona's primary expected output:

Three-layer reconciliation reports per ecosystem project

Operationally: run fcc safe-reconcile against the reference scenario, inspect the output, and present it to one upstream collaborator for review.

Weeks 5–8 — Learn the toolchain

Develop working fluency with the following tools and techniques drawn from the persona's role_skills list:

  • Three-layer documentation convention fluency (Layer 1 / Layer 2 / Layer 3)
  • Markdown structural parsing (front matter, headings, code fences, diagrams)
  • Cross-layer consistency analysis (claim ↔ spec ↔ contract traceability)
  • Layer-collapse detection patterns (protocol schemas in roadmap, roadmap in protocols)
  • Multi-repo reconciliation across the 19-project ecosystem inventory

Pair with a seasoned The Reconciler practitioner from an adjacent persona (see Escalation Points below) for at least two sessions to absorb idiom and discipline.

Weeks 9–12 — First review

By day 90 you should have:

  • Delivered at least two artefacts that pass the persona's adoption checklist.
  • Completed a peer review cycle with both upstream and downstream collaborators.
  • Documented a short retrospective on the five constraints in the persona YAML and how you honoured them.
  • Earned scored entries on at least three of the six discernment traits.

Adoption-checklist targets to hit by day 90:

  • Three-layer presence check run across every ecosystem project
  • Cross-layer contradiction scan complete with cited findings
  • Layer-collapse detection run with severity-triaged findings
  • Ecosystem-wide drift heatmap published
  • Reconciliation reports authored with file + line citations
  • OpenTelemetry spans emitted for the reconciliation pass
  • Remediation pointers handed to owning Documentation Evangelist per project

Reference scenario (from the persona YAML):

Scan the 19-project ecosystem inventory for three-layer documentation presence (ROADMAP/SAR/AGENTS), detect 3 projects missing Layer 3 AGENTS.md, surface 2 cross-layer contradictions where Layer 2 specifies an API that Layer 1 does not promise, flag 1 layer-collapse case where protocol schemas leaked into a ROADMAP, author a drift heatmap, and hand remediation pointers to each project's Documentation Evangelist

Common Pitfalls

Failure modes specific to the TLDR role, drawn from the persona's constraints, the Discernment Matrix, and the cross-reference patterns observed across v1.4.1–v1.5.2.

Role-specific pitfalls

  • Layer conflation — ROADMAP and SAR pulled toward the same voice
  • Reconciling the three layers into one (defeats the separation purpose)
  • Missing AGENTS layer updates — only ROADMAP + SAR get reconciled
  • Reconciliation without diff-audit trail

Constraint-driven pitfalls

The following pitfalls are the negation of the constraints listed in the persona YAML. Violating any of them is a governance signal:

  • Constraint: Observer + reporter only — never modifies ROADMAP.md, SAR, or AGENTS.md
  • Constraint: Every finding must cite source file + line reference
  • Constraint: Layer mixing is a finding, not a preference — Layer 1/2/3 must stay cleanly separated
  • Constraint: Missing-layer drift is P1 (mandatory remediation) per governance constitution
  • Constraint: Defer remediation ownership to the owning project's docs author

Discernment-trait pitfalls

Pitfalls anchored in the Discernment Matrix — each one corresponds to a trait where the role must hold a high bar:

  • Humility drift: Willingness to refine layer heuristics as new ecosystem documentation patterns surface.
  • Professional Background drift: Deep expertise in docs-as-code discipline and multi-repo documentation reconciliation.
  • Curiosity drift: Drive to uncover subtle layer-collapse patterns across ecosystem documentation.
  • Taste drift: Judgment about which layer content belongs to — separating narrative from specification from protocol.
  • Inclusivity drift: Consideration for diverse documentation styles across ecosystem project authors.
  • Responsibility drift: Accountability for reconciliation integrity, citation discipline, and non-modification observance.

Escalation Points

When the TLDR role reaches the edge of its charter, handoffs and escalations flow along the collaboration edges recorded in the persona YAML. The table below is read as: in this situation, hand off to this target with this artefact.

Collaboration graph

Upstream (this persona receives from):

  • SFBI — Consumes translation hints for vocabulary alignment

Peers (bidirectional):

  • SMC — Cross-references PI scorecards to tie doc-drift to PI health

Downstream (this persona hands off to):

  • FA — Reports reconciliation findings for ecosystem-wide evidence graphs
  • DE — Hands remediation pointers for docs authoring
  • GCA — Escalates P0 findings for governance enforcement

Escalation matrix

Situation Escalate to Artefact expected
Constraint violation observed in own output Forensic Auditor (FA) evidence packet with cited constraint + remediation plan
Downstream consumer reports drift from TLDR artefacts SFBI scorecard delta + drift-run manifest
Cross-project handoff required RHL (research) or IHL (innovation) handoff bundle with provenance metadata
IP or patent-claim conflict surfaces in scope PCT (Patent Claim Tracer) claim-to-code map + FTO evidence
Release gating requested but role is not the gate-owner Release Manager (RM) metrics scorecard with explicit non-binding status

Champion promotion. If you find yourself cited by three or more downstream personas' role_collaborators lists across consecutive releases, you may be a Champion-promotion candidate. See ../evolution-pathways.md#when-to-promote for the formal criteria.

See also