customer-card-render

Customer Card Render Skill

Converts canonical Design Thinking markdown artifacts into PowerPoint skill content.yaml slide definitions and builds the final deck through the shared PowerPoint build pipeline.

Overview

This skill is a sibling to the experimental powerpoint skill. It handles the Design Thinking-specific mapping layer: extracting sections from canonical markdown artifacts and filling template-driven content.yaml files. The PowerPoint skill then owns layout rendering, theming, export, and validation.

Keeping these concerns separate means:

• Customer-card mapping logic stays independent from general PowerPoint capabilities.
• The skill can be included in packages independently.
• Layout primitives, Invoke-PptxPipeline.ps1, theming, and validation behavior are not reimplemented here.

For full PowerPoint pipeline documentation, activate the powerpoint skill by name. When it does not resolve, warn the user that the pipeline documentation and build behavior are unavailable and stop rather than reimplementing them here.

Prerequisites

• Python 3.11+

• uv package manager, installed with a package manager that verifies the download against a published hash:

  # Windows
  winget install --id astral-sh.uv -e
  
  # macOS / Linux (Homebrew)
  brew install uv
  

  To install from a release archive instead, download it from the uv releases page and check it against its .sha256 file before extracting.

• The experimental powerpoint skill, activated by name, for the Invoke-PptxPipeline.ps1 build step. When it does not resolve, warn the user that the build step is unavailable and stop.

Directory Structure

.github/skills/experimental/customer-card-render/
├── SKILL.md
├── pyproject.toml
├── references/
│   └── mapping-spec.md
├── scripts/
│   └── generate_cards.py
├── templates/
│   ├── global-style.yaml
│   ├── persona.content.yaml
│   ├── problem.content.yaml
│   ├── scenario.content.yaml
│   ├── use-case-slide1.content.yaml
│   ├── use-case-slide2.content.yaml
│   ├── use-case-slide3.content.yaml
│   └── vision.content.yaml
└── tests/
    ├── fuzz_harness.py
    └── test_generate_cards.py

Supported Artifact Types

Artifact Type	Slide Layout
Vision Statement	Single slide
Problem Statement	Single slide
Scenario	Single slide
Use Case	4 slides (see below)
Persona	Single slide

Use Case 4-Slide Layout

Each Use Case expands into 4 consecutive slides with distinct sections:

Slide	Content
Slide 1	Use Case Description, Use Case Overview, Business Value, Primary User
Slide 2	Secondary User, Preconditions, Steps, Data Requirements
Slide 3	Equipment Requirements, Operating Environment, Success Criteria, Pain Points
Slide 4	Extensions, Evidence

Cards are ordered by artifact type (Vision → Problem → Scenario → Use Case → Persona), then alphabetically by title within each type. Use Cases appear with all 4 slides consecutive (Slide N, N+1, N+2, N+3).

Two-Command Flow

Step 1: Generate slide YAML from canonical markdown

python "<customer-card-render-skill-root>/scripts/generate_cards.py" \
  --canonical-dir .copilot-tracking/dt/<project-slug>/canonical \
  --output-dir .copilot-tracking/dt/<project-slug>/render/content

Resolve <customer-card-render-skill-root> from the loaded skill location before running the command.

generate_cards.py CLI Reference

Flag	Required	Default	Description
--canonical-dir	No	<skill-root>/canonical	Directory containing canonical DT markdown files
--output-dir	No	<skill-root>/scripts/content	Directory to write generated content.yaml files
-v, --verbose	No	—	Enable debug-level logging

The script reads each markdown file in --canonical-dir, detects the artifact type from frontmatter, extracts required sections, and generates content.yaml files. Vision, Problem, Scenario, and Persona artifacts produce one slide each. Use Case artifacts produce 4 consecutive slides per use case.

For the section-to-field mapping contract and Use Case 4-slide layout details, see references/mapping-spec.md.

Step 2: Build PPTX using the PowerPoint skill pipeline

Activate the powerpoint skill by name and hand it the build, supplying these three inputs:

• Content directory: .copilot-tracking/dt/<project-slug>/render/content
• Style path: .copilot-tracking/dt/<project-slug>/render/content/global/style.yaml
• Output path: .copilot-tracking/dt/<project-slug>/render/output/customer-cards.pptx

The powerpoint skill owns the Invoke-PptxPipeline.ps1 orchestrator, its parameter reference, template usage, validation, and export options, and it manages virtual environment setup and dependency installation automatically via uv sync. When that skill is unavailable, warn the user that the build step cannot run and stop rather than invoking the pipeline from a guessed location.

DT Coach Integration

The dt-coaching-foundation skill's canonical-deck reference provides opt-in workflow integration for the Design Thinking coaching agent. When a user opts in, the coaching agent offers to build customer cards at method exit points. The two-command flow above runs as part of that workflow with --canonical-dir and --output-dir resolved from the active DT project slug in .copilot-tracking/dt/.

Canonical artifacts are produced by the DT coach and live under .copilot-tracking/dt/<project-slug>/canonical/.

Running Tests

cd "<customer-card-render-skill-root>"
uv sync --group dev
uv run pytest tests/

Tests cover parsing, template selection, YAML emission, and regressions. The tests/fuzz_harness.py file is an Atheris polyglot fuzz harness for OSSF Scorecard compliance.

Content Fidelity Note: Use Case Cards

Use Case cards are split across 3 opinionated slides, each with dedicated sections:

• Slide 1: Introduces the use case with Description, Overview, Business Value, and Primary User
• Slide 2: Details execution with Secondary User, Preconditions, Steps, and Data Requirements
• Slide 3: Captures quality criteria with Equipment Requirements, Operating Environment, Success Criteria, Pain Points, and Evidence

This structure ensures all 16 Use Case sections fit legibly across 4 slides without compression. Each section appears in its own textbox with appropriate styling and heading.

For complete mapping details, see references/mapping-spec.md.

Troubleshooting

Issue	Cause	Solution
uv not found	uv not installed	Run winget install --id astral-sh.uv -e (Windows) or brew install uv (macOS/Linux)
Python not found by uv	No Python 3.11+ on PATH	Run uv python install 3.11
Template not found	--canonical-dir contains unknown type	Check frontmatter type: field against supported artifact types
Empty output directory	No canonical markdown files found	Confirm --canonical-dir path and that files have --- frontmatter
PPTX build fails after generate	PowerPoint skill missing or not activated	Activate the powerpoint skill by name. When its content does not arrive, stop and report the build step as unavailable