Brainforge Knowledge

README

8 min read

Data service line — templates and documentation standards

Owner: Data Platform service line Last updated: 2026-05-01

Template registry

Status#Document typeFileInit skillNotes
✅A1Data Source Discovery Memo (with Changelog + Schema Audit appendix + SLA)data-source-discovery-memo-template.md✅ discovery-memo-initAbsorbed A2 (changelog), A4 (schema audit), and SLA/Data Contract
✅A3Executive-style Discovery Memoexecutive-discovery-memo-template.md✅ executive-discovery-memo-initOne-pager for leadership
✅B1Data Findings Memodata-findings-memo-template.md✅ data-findings-memo-initUpgraded + init skill
✅B2RCA Memo (incidents + KPI anomalies)rca-memo-template.md✅ rca-memo-initUpgraded + init skill
✅C4Technical Design Document (TDD) — Datatdd-data-template.md✅ tdd-data-initCreated fresh + init skill
✅D1Metrics Definition Documentmetrics-definition-doc-template.md✅ metrics-definition-initUpgraded + init skill
✅D2Golden Dataset Specgolden-dataset-spec-template.md✅ golden-dataset-spec-initEvaluation dataset for NL2SQL
✅E1ETL Migration Planmigration/etl-migration-plan-template.md✅ etl-migration-plan-initCutover playbook for tool migration
✅E2Data Warehouse Migration Planmigration/warehouse-migration-plan-template.md✅ warehouse-migration-plan-initCutover playbook for platform migration
✅E3Data Platform Documentation (Google Sheet + companion)data-platform-locked-metrics-template.md✅ data-platform-docRepo companion for sheet metric definitions

Legend: ✅ = template + init skill done · 🟡 = template exists, needs upgrade or skill · 🔴 = gap (no template)

Adjacent (Strategy & Analytics):

Document typeFilePurpose
Dashboard Specification../../strategy-analytics/templates/dashboard-specification-template.mdClient dashboard spec (§1–§12) — the exemplar this suite follows

Consolidation notes

Former standalone typeNow lives inHow
A2 — Discovery Memo UpdateA1 Discovery Memo§11 Changelog (date-stamped entries, newest first)
A4 — Schema AuditA1 Discovery MemoAppendix C (per-table column catalog)
B4 — KPI Anomaly DetectionB2 RCA MemoType metadata field: [Incident / KPI Anomaly]
D2 — Data Contract / SLAA1 Discovery Memo§2.3 Freshness SLA table
E2 — Data SOWRemoved from Data suiteBelongs to Sales/GTM; referenced only in Related Artifacts

Template directory structure

Templates live in two locations: canonical Data templates under data/templates/, and shared Brainforge memo templates under standards/02-writing/Memos/. Both are listed in the registry above with full paths.

knowledge/delivery/service-lines/data/templates/
├── README.md                                    # this file — registry
├── DATA_DOCUMENTATION_SUITE_BLUEPRINT.md        # full suite architecture
├── data-source-discovery-memo-template.md       # A1 (changelog + schema appendix + SLA)
├── executive-discovery-memo-template.md         # A3
├── data-quality-assessment-template.md          # B3
├── modeling-design-doc-template.md              # C1
├── warehouse-architecture-assessment-template.md # C3
├── tdd-data-template.md                         # C4
├── golden-dataset-spec-template.md              # D2
├── data-platform-locked-metrics-template.md     # E3 companion
├── vendor/
│   └── snowflake/
│       └── semantic-view-design-doc-template.md # C2 [Snowflake]
└── migration/
    ├── etl-migration-plan-template.md           # E1
    └── warehouse-migration-plan-template.md     # E2

# Shared memo templates (live outside data/templates/):
knowledge/standards/02-writing/Memos/
├── data-findings-memo-template.md               # B1
├── rca-memo-template.md                         # B2 (incidents + anomalies)
├── metrics-definition-doc-template.md           # D1
└── technical-assessment-memo-template.md        # legacy

What makes a great template (principles)

Every canonical template in this repo should satisfy these checks. The principles are rooted in three proven traditions: the Minto Pyramid Principle (McKinsey’s framework for structured communication, now the standard across MBB consulting and business schools globally), MBB consulting slide/doc standards (action titles, SCR, MECE, one message per unit), and Stripe/Amazon developer docs (example-first, object navigation, error documentation as top-level content).

Structure — rooted in the Pyramid Principle (Minto/McKinsey)

“Lead with the answer, support with logic. Information should be organized in a pyramid where the main idea sits at the top and supporting arguments flow below.” — Barbara Minto, former McKinsey consultant, The Pyramid Principle (1978, still the standard across MBB consulting and taught at Harvard, INSEAD, Wharton).

  • Pyramid structure: answer first — The document opens with the recommendation or key finding (the top of the pyramid), not background or history. Supporting detail follows in numbered sections. This is non-negotiable for decision-oriented documents. Source: Minto Pyramid Principle, adopted by McKinsey, Bain, BCG, Amazon as the standard for business communication.
  • SCR executive summary — The executive summary follows Situation-Complication-Resolution: what is true, what changed or is broken, what we should do about it. Source: McKinsey/BCG/Bain standard for executive summaries; the most effective format for busy decision-makers across consulting and tech.
  • Numbered sections — stable, predictable structure; append-only renumbering. Each section has an action-title heading (a complete sentence takeaway), not a topic label. Reading just the section headings tells the full story. Source: MBB slide standards — “action titles state the takeaway, not the topic.” BCG: “Reading only the titles tells the complete story.”
  • One message per section — If you have two distinct points, make two sections. Never overload a section with a second message. Source: MBB consulting standard — “Each slide communicates exactly one insight. If you have two points, make two slides.”
  • MECE grouping — Sections at each level are Mutually Exclusive (no overlap) and Collectively Exhaustive (no gaps). Source: Minto Pyramid Principle — arguably the most widely adopted consulting framework globally.
  • “When to use” vs “when NOT to use” — differentiation from adjacent templates. Saves readers from picking the wrong template and producing a document that doesn’t serve its purpose.
  • Related artifacts table — links to Data Platform, Linear, legacy, parent docs. Every document is part of a system, not an island.
  • Fill-in-the-blank format — [placeholders] with example values inline. Mirroring Stripe’s approach of matched, curated examples per endpoint — every placeholder shows what good looks like. Source: Stripe API docs — “every endpoint has a matched, curated code example for every language” — applied to templates: every field has a concrete example.
  • Closed set of sections — no “miscellaneous” or “other” buckets. If something doesn’t fit, the taxonomy is wrong. Source: MECE principle — “Collectively Exhaustive” means the sections cover everything without needing a catch-all.

Audience — rooted in MBB dual-audience design

“Keep the narrative for the decision-maker; move the detail to the appendix.” — McKinsey document design principle.

  • Dual-audience calibration — executive summary at the top for the sponsor (60-second read), technical detail in dedicated sections for the implementer. BCG’s approach: “Situation in 1-2 sentences, Complication in 1 sentence, Resolution taking 70-80% of the page.” Source: MBB standard — the SCR executive summary is explicitly designed for executive consumption; appendix is explicitly designed for implementers.
  • Action-title headings — Every section heading is a complete sentence that communicates the takeaway. A reader scanning headings should understand the entire argument without reading the body. Source: BCG/McKinsey slide standard — “When done right, you should be able to read just the titles of a presentation and understand the core argument.” BCG requires action titles on every slide: “State specific, quantitative insights in 15 words or fewer.”
  • 60-second skim test — a director can read §1 in two minutes and know what landed and why.
  • Builder-readable — an analyst can find grain, caveats, and join keys without reading marketing language.

Quality — rooted in consulting QA rigor and Stripe-level documentation discipline

“Source everything. Consistent formatting. No drafts shipped.” — MBB slide quality standards.

  • Anti-fluff guardrails embedded — banned phrases, filler patterns called out in the template. Every consultancy trains its juniors to cut fluff; this hardcodes that training into the template itself. Source: BCG/McKinsey — “Eliminate unnecessary words and sentences. Keep it as simple and short as possible.” McKinsey: “Clear means your document structure must be logical, easily understandable, and set up in a visually appealing way.”
  • Validation/QA section — how to verify correctness before shipping. Source: MBB slide quality checklist — systematic review before delivery: Are figures correct? Are sources included? Are fonts consistent? Are colors correct?
  • “Decisions made (and how to override them)” pattern — every non-obvious choice is documented and reversible. Prevents the “but why did you do it that way?” loop.
  • Example values showing what good looks like — not conceptual, concrete. Source: Stripe API docs — the most copied developer docs pattern: matched, curated examples per endpoint that are kept in sync with the reference.
  • Change log or versioning discipline — new entries at top, date-stamped.
  • Source everything — any quantitative claim or data reference includes a source line. Source: MBB slide standards — “No data without attribution. Source line required for any quantitative claim.”

Repository hygiene

  • Single source of truth declared — which artifact wins when two disagree. Prevents the “which version is current?” problem that plagues consulting deliverables.
  • Filename convention — {client}-{domain}-{type}.md under knowledge/clients/{client}/resources/.
  • Template lives in templates/ — not duplicated in client folders.
  • Skill or playbook references the template — agents know where to find it.

Exemplars (best-in-class)

DocumentWhy it’s the exemplar
Dashboard specification template (strategy-analytics/templates/dashboard-specification-template.md)Gold standard: 465 lines, 12 numbered sections, dual-audience, “About this document” conventions, QA checklist appendix, embedded guardrails, fill-in-the-blank with concrete examples
Data Findings Memo template (standards/02-writing/Memos/data-findings-memo-template.md)Clean: “When to use” section, differentiating from adjacent templates, “Decisions made (and how to override)” pattern, validation queries, audience-aware
LMNT Shopify Discovery Memo (knowledge/clients/lmnt/resources/_gdoc_import_ready_2026-04-15/LMNT_Discovery_Memo_Shopify.md)Real-world example of a well-structured discovery memo with per-table catalog, cross-cutting questions, and executive summary that passes the 60-second test

Implementation phases

Phase 1 — Foundation (U1–U3)

Blueprint finalization, A1 consolidation (changelog + schema appendix + SLA), README rewrite. Done.

Phase 2 — Priority gaps

Modeling Design Doc (C1), Data Quality Assessment (B3), Executive Discovery Memo (A3). Each with template + init skill.

Phase 3 — Upgrade existing

Data Findings Memo + Metrics Definition Doc — bring to quality bar with init skills. RCA Memo — upgrade + absorb KPI anomaly subtype.

Phase 4 — Technical & contract

Semantic View (vendor/snowflake/, client-facing), Warehouse Assessment, Golden Dataset, TDD Data upgrade.

Phase 5 — Migration + cross-cutting

ETL Migration, Warehouse Migration, Data Platform companion, remaining init skills.

See docs/plans/2026-05-01-001-feat-data-documentation-suite-plan.md for full plan with 17 implementation units.

Graph View