customer-card-render

Customer Card Render Skill

Converts canonical Design Thinking markdown artifacts into template-driven content.yaml slide definitions.

Overview

This skill handles the Design Thinking-specific mapping layer: extracting sections from canonical markdown artifacts and filling template-driven content.yaml files. It does not build, theme, export, or validate a presentation file. The separate hve-slides skill owns HTML presentation authoring and rendering.

Keeping this layer separate means:

• Customer-card mapping logic stays independent from any presentation tooling.
• The skill can be included in packages independently.
• The generated YAML stays a reviewable, renderer-neutral artifact.

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.

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

Use Case 4-Slide Layout

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

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).

Generate Slide YAML

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

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.

The generated content.yaml files are this skill's final output. For an explicitly requested HTML presentation, hand reviewed YAML to hve-slides authoring. For a levelled demo, use hve-demo-material and its references/slide-content.md adapter contract. Resolve skills by name, preserve canonical order, source labels and unknown-knowledge markers, and never claim a presentation exists until rendered and validated. This mapping skill does not synthesize narration or dispatch a deck subagent.

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 generate customer-card YAML at method exit points. The generation command 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