Customer Card Render

description: "Canonical markdown section-to-field mapping for customer-card generation"

<!-- markdownlint-disable-file -->

Customer Card Mapping Spec

This spec defines only canonical section extraction and field mapping.

Layout, sizing, theming, rendering, export, and validation behavior are out of scope; this skill emits renderer-neutral content.yaml.

Canonical Source Structure

canonical/
├── vision-statement.md
├── problem-statement.md
├── scenarios/
│   └── *.md
├── use-cases/
│   └── *.md
└── personas/
    └── *.md

Metadata Mapping

Support both metadata naming variants:

• Artifact type or Source artifact type

• Source path or Source file path

• Last updated (fallback to current date)

Text Normalization Behavior

The generator normalizes section content before rendering:

• Hard-wrapped prose lines are unwrapped into single-line paragraphs.

• Paragraph boundaries are preserved.

• Markdown list item boundaries are preserved.

This avoids visual line wrapping artifacts caused by canonical markdown hard wraps while preserving intentional list formatting.

Field Mapping by Card Type

Vision Statement

Required sections:

• Title: frontmatter title, else first heading

• ## Vision Statement (primary vision)

• ### Why This Matters (secondary rationale)

Generator Implementation: _vision_sections() extracts both sections into individual placeholders: V_VISION_STATEMENT, V_WHY_THIS_MATTERS.

Template Design: Two textboxes on a single slide with dedicated headers ("Vision Statement" and "Why This Matters"). Each section displays separately with appropriate sizing.

Problem Statement

Required sections:

• Title: frontmatter title, else first heading

• ## Problem Statement (the problem to solve)

Generator Implementation: _problem_sections() extracts the Problem Statement section into placeholder: P_PROBLEM_STATEMENT.

Template Design: Single textbox on a slide. Well-suited to accommodate typical problem statements without overflow.

Scenario

Required sections in order:

1. ### Description

2. ### Scenario Narrative

3. ### How Might We

Generator Implementation: _scenario_sections() extracts all three sections into individual placeholders: SC_DESCRIPTION, SC_SCENARIO_NARRATIVE, SC_HOW_MIGHT_WE.

Template Design: Three section-title textboxes plus three dedicated content textboxes on a single slide. "Description", "Scenario Narrative", and "How Might We" use the same visual section-title styling pattern as Use Case field sections.

Use Case

Use Case artifacts are split across 4 slides. Each slide has dedicated sections with no aggregation or truncation.

Slide 1: Use Case Overview

Required sections:

1. ### Use Case Description

2. ### Use Case Overview

3. ### Business Value

4. ### Primary User

Generator Implementation: _use_case_slide1() extracts these sections into the slide1 template placeholders: UC_DESCRIPTION, UC_OVERVIEW, UC_BUSINESS_VALUE, UC_PRIMARY_USER.

Slide 2: Use Case Execution

Required sections:

1. ### Secondary User

2. ### Preconditions

3. ### Steps

4. ### Data Requirements

Generator Implementation: _use_case_slide2() extracts these sections into the slide2 template placeholders: UC_SECONDARY_USER, UC_PRECONDITIONS, UC_STEPS, UC_DATA_REQUIREMENTS.

The slide 2 template also uses UC_PRIMARY_USER to display the primary user alongside secondary user for continuity across use-case parts.

Slide 3: Use Case Quality & Context

Required sections:

1. ### Equipment Requirements

2. ### Operating Environment

3. ### Success Criteria

4. ### Pain Points

Generator Implementation: _use_case_slide3() extracts these sections into the slide3 template placeholders: UC_EQUIPMENT_REQUIREMENTS, UC_OPERATING_ENVIRONMENT, UC_SUCCESS_CRITERIA, UC_PAIN_POINTS.

Slide 4: Use Case Extensions & Evidence

Required sections:

1. ### Extensions

2. ### Evidence

Generator Implementation: _use_case_slide4() extracts these sections into the slide4 template placeholders: UC_EXTENSIONS, UC_EVIDENCE.

Template Design: Two textboxes on a slide with dedicated headers. Extensions receives more vertical space (2.8") to accommodate typical extension content, while Evidence uses a smaller section (0.7").

Note: All Use Case slides appear consecutively in the final deck (e.g., Use Case "Project Alpha" generates slides 5, 6, 7, 8).

Persona

Required sections:

1. ### Description

2. ### User Goal

3. ### User Needs

4. ### User Mindset

Generator Implementation: _persona_sections() extracts all four sections into individual placeholders: PE_DESCRIPTION, PE_USER_GOAL, PE_USER_NEEDS, PE_USER_MINDSET.

Template Design: Four textboxes on a single slide, each with a dedicated header and section content. Sections stack vertically without aggregation or truncation.

Narrative Ordering

Output ordering follows DT discovery progression with Use Cases expanded into 4 slides:

1. Vision Statement (slide 1)

2. Problem Statement (slide 2)

3. Scenarios (alphabetical, one slide each)

4. Use Cases (alphabetical, 4 slides each per Use Case)

5. Personas (alphabetical, one slide each)

Example with 2 scenarios, 1 use case, 1 persona:

• Slide 1: Vision Statement

• Slide 2: Problem Statement

• Slide 3: Scenario "Customer onboarding"

• Slide 4: Scenario "Post-launch support"

• Slide 5-8: Use Case "Enterprise deployment" (4 slides)

• Slide 9: Persona "Infrastructure engineer"

Missing Data Contract

If canonical sections use <insufficient knowledge>, preserve it verbatim in generated slide fields. The generator must not invent replacement content.