dl-databook-narrative

name: dl-databook-narrative description: > Synthesizes a structured MD&A-style narrative (markdown + JSON) from the populated P6 analytical workbooks (Databook vS + Overland Model vS) plus optional management commentary. Use at P6 after dl-databook-financials / -charts / -kpi / -model when the user asks to "write the databook narrative," "synthesize the MD&A," or "summarize what the workbooks say." Eight catalog categories; every item carries a verifiable workbook-cell, manifest-field, or commentary-excerpt basis (anti-fabrication); unions every upstream escalation, [INSUFFICIENT DATA] marker, tie miss, and validation-cross-check escalation into one severity-classified data-gap list. Feeds dl-ddq-initial and dl-memo-prescreen. Internal-only CONFIDENTIAL; reads no RESTRICTED input; the draft banner is the literal first line of the markdown.

dl-databook-narrative — P6 Databook + Overland Model narrative synthesis

When to use

Use this skill when the user has the four P6 analytical workbook outputs available (the populated vS Databook from dl-databook-financials, optionally the chart-restored vS from dl-databook-charts, optionally one or more KPI tabs from dl-databook-kpi, and the populated vS Overland Model from dl-databook-model) and needs a structured MD&A-style narrative synthesis: the qualitative layer that lets the credit-officer reader scan what the workbooks said happened, who said it, and on what basis. The narrative feeds the Initial DD list (dl-ddq-initial) and the Pre-Screen memo (dl-memo-prescreen).

Do not use this skill to: rebuild any upstream workbook (the four analytical skills run first and produce the basis facts this skill synthesizes from); read the IC debrief punchlist (RESTRICTED — never consumed by this skill); generate narrative text for the outbound DD list directly (that is dl-ddq-initial's job — this skill produces the internal seed; the gap-aware-drafting discipline strips internal-data citations from the outbound text); invent a category outside the eight catalog categories (catalog-shaped or escalate to category_escalations).

What the skill does

A single-call atomic synthesis in five moves: structural read of the upstream workbooks + their structured-output JSON dumps; the deterministic data-gap union + basis-fact computation (the script); the optional defensively-degrading management-commentary cascade; LLM synthesis of narrative items from the basis facts; and the markdown + JSON emit. The script is the deterministic core — the LLM constructs narrative items from the computed basis facts, never computes them itself. The full mechanics are the Workflow below.

Dependencies

pip install openpyxl

(used for the structural read of the two workbooks; the union/basis math is standard-library).

Inputs

The skill expects these inputs at Turn 1:

• Populated Databook (vS) — dl-databook-financials output .xlsx
  • its structured-output JSON.
• Populated Overland Model (vS) — dl-databook-model output .xlsx
  • its structured-output JSON.
• Charts manifest (optional) — the dl-databook-charts output JSON. Absent ⇒ no chart-related gaps surfaced; not a hard dependency.
• KPI cut JSON list (optional) — every KPI tab built by dl-databook-kpi, as a list of instances. Absent ⇒ no KPI-related gaps or concentration facts surfaced.
• Stage-3 deal context — populated by the Stage-3 project instruction's behavioral rules; company_name, as_of_date, SHAREPOINT_DEAL_FOLDER (for the commentary cascade).
• <management_commentary> (optional) — explicit list of commentary documents to consume (overrides / supplements the cascade).

Outputs

• [Company] - Databook Narrative (MM-DD-YY) vS.md — the rendered markdown (with [DRAFT — HUMAN REVIEW REQUIRED] as the literal first line).
• [Company] - databook-narrative-manifest.json — the skill's structured-output JSON projection.
• [Company] - narrative_basis.json — the per-category quantitative basis facts (the synthesis script's intermediate; useful for re-running synthesis with refreshed workbook outputs).
• [Company] - data_gaps.json — the deterministic data-gap union (the synthesis script's other intermediate).

Workflow

Turn 1 — confirm inputs + plan. Read the populated Databook + Overland Model structurally (sheet names, key cell addresses confirmed); load the upstream skills' structured-output JSON dumps; identify any KPI cuts to consume. Surface to the user:

• The resolved company name + as-of date.
• The upstream artifact inventory (Databook present? Overland Model present? Charts manifest present? KPI cuts available count?).
• The proposed commentary cascade order (project → chat → MSFT 365) with any documents already found in the project's ACTIVE DOCUMENT INDEX.
• Any anticipated category escalations (e.g., the CIM mentions a litigation matter that would escalate per the bespoke-shape rule).

If <management_commentary> is supplied explicitly, list the documents that will be read. Wait for user confirmation.

Turn 2 — execute the synthesis.

1. Run python scripts/synthesize_narrative.py --databook-payload <financials.json> --charts-payload <charts.json optional> --kpi-payloads <kpi-cuts.json optional> --model-payload <overland-model.json> --databook-path <populated_databook_vS.xlsx> --overland-model-path <populated_overland_model_vS.xlsx> --out-basis narrative_basis.json --out-gaps data_gaps.json — the JSON arguments are each upstream skill's structured-output dump (financials from dl-databook-financials, charts from dl-databook-charts if present, KPI cuts from dl-databook-kpi, the model build from dl-databook-model). The script emits the two intermediates and prints a summary line with counts + the synthesis signature.
2. Execute the management-commentary cascade per the reference/synthesis-construction.md discipline; record the commentary_sources[] and the commentary_basis provenance.
3. LLM synthesis — construct narrative items from the basis facts + any commentary excerpts. Apply the basis-citation discipline (every item carries a verifiable basis citation); apply the severity classification (default consideration for data_gap items, upgrade to critical or downgrade to informational with a recorded severity_reason); apply the catalog-shaped-or-escalate rule (escalate bespoke shapes to category_escalations, never invent a ninth category); apply the case-comparison discipline (all three cases cited, dollar / % deltas surfaced).
4. Emit the markdown ([DRAFT — HUMAN REVIEW REQUIRED] first line; the section order per reference/narrative-schema.md) + the JSON manifest (the skill's structured-output projection). Validate the schema before writing.

On a basic synthesis (full inputs, no commentary): present the manifest summary (narrative item counts by severity + category; data_gap counts; commentary_basis; synthesis_signature).

On a degraded synthesis (model absent / databook absent / both absent): present the degraded narrative with the data_gaps[] entries explaining the missing inputs; the human reviewer decides whether to re-run after producing the missing upstream artifacts.

Re-run idempotence. A second call with the same synthesis_signature returns narrative_already_built (the script's output is identical; the LLM-synthesized markdown is intent-equivalent). To force re-synthesis (e.g., after an upstream workbook update), pass --rebuild (re-emits the markdown + JSON with the new signature).

Constraints

• Anti-fabrication is non-negotiable. Every narrative item carries a verifiable basis citation. A finding without a traceable basis is refused with [INSUFFICIENT DATA — narrative basis untraceable], not paraphrased into existence.
• Catalog-shaped or escalate. A finding that doesn't fit one of the eight categories (revenue_trajectory / margin_trajectory / capex_intensity / nwc_cycle / concentration / case_comparison / data_gap / variance) escalates to category_escalations with a named reason. The skill never invents a ninth category.
• The data-gap union is exhaustive. The script's data_gaps.json is the source of truth; the LLM cannot drop a gap. It can re-classify severity (consideration → critical upgrade; consideration → informational downgrade) only with a recorded severity_reason.
• The management-commentary cascade is defensively-degrading. Project → chat → Microsoft 365 → workbooks-only. The connector is never a hard dependency; a connector NOT_FOUND / ACCESS_DENIED / not-connected is never retried and never silently treated as "succeeded". Cite commentary verbatim (≤200 chars quote); never paraphrase.
• No upstream-skill modification. The four analytical workbook skills, the IC debrief skill, their schemas, scripts, and preservation gates are not modified by this skill — it reads them only, over the documented public surfaces.
• The downstream contract for dl-ddq-initial is binding. Items with severity in {consideration, critical} and downstream_consumer including dd_list are eligible for the DD list feed; items with data_gap category become data requests, other categories become diligence questions (per the framework-spine group mapping). The basis field is consumed but never echoed — the basis-internal / question-outbound discipline is the dl-ddq-initial outbound-redaction firewall.

References

• reference/narrative-schema.md — the dependency-chain root. The markdown + JSON output schema; the eight categories; the per-item field definitions (narrative item, data gap, basis record, commentary source); the upstream-consumed surface manifest (which fields the synthesis script reads from each upstream skill); the filtered projection consumed by dl-ddq-initial; the markdown section order.
• reference/synthesis-construction.md — the analytical core. The eight narrative categories with worked examples per category; the basis-citation discipline (anti-fabrication rule) with worked good/bad rewrites; the severity classification with credit-judgment criteria; the management-commentary cascade with the defensively-degrading order; the bespoke-shape escalation; the case-comparison narrative discipline.

Classification & review state

The narrative is internal (CONFIDENTIAL) — never outbound, never co-lender/LP-shared; no outbound-redaction checklist applies. It reads no RESTRICTED input (the IC debrief punchlist is never consumed). The output is a draft pending human review: because the deliverable is generated markdown, not an edited production template, [DRAFT — HUMAN REVIEW REQUIRED] is the literal first line of the markdown (the vS filename carries the same signal). A reviewer approves; never approve, finalize, or issue. [INSUFFICIENT DATA — <what is missing>] is the only uncertainty marker.

Runtime

The synthesis script runs where Python is available: Claude Desktop or claude.ai with code execution enabled. In an Office add-in (or any chat without code execution), do not improvise the data-gap union or the basis math by hand — the script is the deterministic core; say so and direct the user to run the skill in Claude Desktop (discussing upstream findings still works anywhere). The Microsoft 365 connector (commentary cascade) uses fully-qualified Server:tool names; confirm the server name at first invocation.