ADR-141: Pitch Deck Mastery v3.0 Interactive Workflow Architecture

Status

ACCEPTED - 2026-01-29

Context

The pitch-deck-mastery skill (v2.2.0) provides comprehensive pitch deck creation capabilities but lacks:

Interactive input collection - No structured questions for logo, content paths, founder photos
Brand color extraction - Manual color specification required
Content auto-discovery - No automatic scanning of source materials
Slide-by-slide editing - No iterative review/edit workflow
Final approval workflow - No structured approval checkpoint

Users requested enhanced interactivity with:

Multiple path inputs for different content types
URL-based color extraction from company websites
Forward/back navigation during slide editing
Approval checkboxes with verification loops

Decision

Implement pitch-deck-mastery v3.0 with four implementation phases:

Phase A: Enhanced Input Collection + Color Extraction

Input Questions via AskUserQuestion:

Content Source (header: "Content")
- "Provide path(s)" - Manual path entry
- "Auto-discover from project" - Scan common locations
- "Import from URL" - Web scraping mode
Logo (header: "Logo")
- Path to logo file
- URL to download
- "Extract from website"
Founder Photos (header: "Photos")
- Multi-select for multiple path entries
- Directory scanning option
Slide Framework (header: "Framework")
- FAU Runway (11 slides)
- YC Demo Day (8 slides)
- Custom slide requirements file
Website URL (header: "Brand")
- Input URL for color extraction
- Fallback to default palette

Color Extraction Workflow:

URL Input → WebFetch → CSS Extraction → Color Analysis → design-theme-sheet.md

Phase B: Content Auto-Discovery + Mapping

Auto-Discovery Logic:

Given path(s), scan for:
├── Pitch sources: **/pitch*.md, **/investor*.md, **/deck*.md
├── Financial data: **/financials*.md, **/projections*.md
├── Team info: **/team*.md, **/founders*.md, **/about*.md
├── Market research: **/market*.md, **/competitive*.md, **/tam*.md
└── Product info: **/product*.md, **/features*.md, **/roadmap*.md

Content Mapping Pipeline:

Extract key metrics (TAM/SAM/SOM, pricing, team size)
Identify bullet points and summaries
Map content → slide requirements
Generate slide-content-mapping.json

Phase C: Slide-by-Slide Edit Loop

Edit Loop State Machine:

┌─────────────────────────────────────────────────────┐
│                 SLIDE EDITOR STATE                   │
├─────────────────────────────────────────────────────┤
│ Current Slide: 3/11                                 │
│ Status: ○ ○ ● ○ ○ ○ ○ ○ ○ ○ ○  (● = current)       │
│                                                     │
│ [< Prev] [Next >] [Preview] [Regenerate] [Approve]  │
└─────────────────────────────────────────────────────┘

Per-Slide AskUserQuestion:

{
  question: "Slide 3: Business Model",
  header: "Slide 3",
  options: [
    { label: "Approve", description: "Content looks good" },
    { label: "Edit content", description: "Modify text/data" },
    { label: "Change layout", description: "Try different layout" },
    { label: "Go back", description: "Return to previous slide" }
  ]
}

Phase D: Final Approval Workflow

Three-Stage Approval:

Quick Review - Thumbnail grid of all slides
Slide-by-Slide Review - Individual approval per slide
Final Confirmation - Checkbox approval + export

State Tracking:

{
  "slide_approvals": [true, true, false, true, ...],
  "edit_history": [...],
  "final_approved": false,
  "export_ready": false
}

Phase E: Web-Based Pitch Deck Studio

Rationale: CLI-based AskUserQuestion workflow has significant UX limitations:

No back navigation (can't return to previous steps)
No visual progress indicator
No real-time preview of build progress
No persistent state across sessions

Solution: Full-featured web GUI with 3-panel layout, deployable to Google Cloud Run or runnable locally via Docker.

Technology Stack:

Component	Technology
Framework	Next.js 14 (App Router, standalone output)
Language	TypeScript
Styling	Tailwind CSS (dark theme)
State	Zustand with persist middleware
UI Components	Radix UI (Progress, Tabs, Select, Dialog)
Icons	Lucide React
PPTX Generation	PptxGenJS (server-side)
Deployment	Docker → Google Cloud Run

3-Panel Layout:

┌─────────────────────────────────────────────────────────────────┐
│  HEADER: Logo + Version + Settings                               │
├────────────┬──────────────────────────────┬─────────────────────┤
│            │                              │                     │
│   FILE     │      WIZARD PANEL            │    PREVIEW          │
│  MANAGER   │                              │     PANEL           │
│            │  ┌──────────────────────┐    │                     │
│  • Assets  │  │ Progress: ● ● ○ ○    │    │  Live preview       │
│  • Exports │  │ Step 4/11: Colors    │    │  of current         │
│  • History │  │                      │    │  slide/deck         │
│            │  │ [Form inputs]        │    │                     │
│   (w-56)   │  │                      │    │   (w-96)            │
│            │  │ [< Back] [Next >]    │    │                     │
│            │  └──────────────────────┘    │                     │
├────────────┴──────────────────────────────┴─────────────────────┤
│  STATUS BAR: Company • Framework • Colors • Progress             │
└─────────────────────────────────────────────────────────────────┘

11-Step Wizard Flow:

Step	Component	Purpose
0	welcome-step	Features overview, Get Started
1	framework-step	Select slide framework (FAU, YC, Seed, Custom)
2	company-step	Company name, tagline, website, funding stage
3	colors-step	Brand colors (extract from URL or preset palettes)
4	team-step	Founders (name, title, bio) - dynamic list
5	contact-step	Contact info for final slide
6	footer-step	Footer options (copyright, confidential, page numbers)
7	content-step	Content ingestion from files
8	editor-step	Slide-by-slide content editing
9	review-step	Full deck review with thumbnails
10	export-step	PPTX export and download

Zustand State Store:

interface DeckStore {
  // Config
  config: DeckConfig
  updateConfig: (partial: Partial<DeckConfig>) => void

  // Navigation
  currentStep: number
  setStep: (step: number) => void
  nextStep: () => void
  prevStep: () => void

  // Slides
  slides: SlideContent[]
  slideApprovals: boolean[]
  approveSlide: (index: number) => void
  updateSlide: (index: number, content: Partial<SlideContent>) => void

  // Export
  exportReady: boolean
  exportDeck: () => Promise<Blob>

  // Reset
  reset: () => void
}

Docker Deployment:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 8080
ENV PORT=8080
CMD ["node", "server.js"]

Cloud Run Configuration:

# cloudbuild.yaml
steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'gcr.io/$PROJECT_ID/pitch-deck-studio:$SHORT_SHA', '.']
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'gcr.io/$PROJECT_ID/pitch-deck-studio:$SHORT_SHA']
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    args:
      - 'gcloud'
      - 'run'
      - 'deploy'
      - 'pitch-deck-studio'
      - '--image=gcr.io/$PROJECT_ID/pitch-deck-studio:$SHORT_SHA'
      - '--region=us-central1'
      - '--platform=managed'
      - '--allow-unauthenticated'

Design Theme (GxP LIMS-inspired):

// tailwind.config.ts colors
colors: {
  background: 'hsl(222, 47%, 11%)',      // Dark navy
  foreground: 'hsl(210, 40%, 98%)',      // Off-white
  card: 'hsl(222, 47%, 13%)',            // Slightly lighter
  primary: 'hsl(217, 91%, 60%)',         // Blue accent
  secondary: 'hsl(222, 47%, 20%)',       // Muted background
  accent: 'hsl(45, 93%, 47%)',           // Gold highlights
  muted: 'hsl(215, 20%, 65%)',           // Gray text
  destructive: 'hsl(0, 84%, 60%)',       // Red for errors
}

Integration with v3.0 Scripts: The web UI integrates with existing Phase A-D scripts:

color-extractor.js → API route for color extraction
content-scanner.py → API route for content discovery
slide-generator.js → Server-side PPTX generation
edit-loop-workflow.js → State synchronization

Architecture

File Structure

skills/pitch-deck-mastery/
├── SKILL.md                    # Main skill (v3.0.0)
├── scripts/
│   ├── color-extractor.js      # Web color extraction
│   ├── content-scanner.py      # Auto-discovery logic
│   ├── slide-generator.js      # PptxGenJS generation
│   └── edit-loop-state.json    # Edit loop state
├── templates/
│   ├── fau-runway-11.json      # FAU Runway (11 slides)
│   ├── yc-demo-day-8.json      # YC Demo Day (8 slides)
│   ├── seed-round-10.json      # Seed round (10 slides)
│   └── custom-schema.json      # Custom template schema
├── themes/
│   ├── default-enterprise.yaml # Navy/blue professional
│   ├── startup-bold.yaml       # Bold startup colors
│   └── minimal-clean.yaml      # Clean minimal theme
├── outputs/
│   └── design-theme-sheet.md   # Generated from URL
│
└── studio/                     # Phase E: Web-based GUI
    ├── package.json            # Next.js + dependencies
    ├── tailwind.config.ts      # Dark theme configuration
    ├── Dockerfile              # Cloud Run deployment
    ├── docker-compose.yml      # Local development
    ├── cloudbuild.yaml         # GCP CI/CD
    │
    ├── src/
    │   ├── app/
    │   │   ├── layout.tsx      # Root layout
    │   │   ├── page.tsx        # Main 3-panel layout
    │   │   └── api/            # API routes for PPTX generation
    │   │
    │   ├── components/
    │   │   ├── ui/             # Shared UI components
    │   │   │   ├── header.tsx
    │   │   │   └── status-bar.tsx
    │   │   │
    │   │   ├── wizard/
    │   │   │   ├── wizard-panel.tsx
    │   │   │   └── steps/      # 11 wizard step components
    │   │   │       ├── welcome-step.tsx
    │   │   │       ├── framework-step.tsx
    │   │   │       ├── company-step.tsx
    │   │   │       ├── colors-step.tsx
    │   │   │       ├── team-step.tsx
    │   │   │       ├── contact-step.tsx
    │   │   │       ├── footer-step.tsx
    │   │   │       ├── content-step.tsx
    │   │   │       ├── editor-step.tsx
    │   │   │       ├── review-step.tsx
    │   │   │       └── export-step.tsx
    │   │   │
    │   │   ├── file-manager/
    │   │   │   └── file-manager.tsx
    │   │   │
    │   │   └── preview/
    │   │       └── preview-panel.tsx
    │   │
    │   └── lib/
    │       └── state/
    │           └── deck-store.ts  # Zustand state management
    │
    └── public/
        └── logo.svg

Workflow Diagram

┌─────────────────────────────────────────────────────────────┐
│                    PITCH DECK MASTERY v3.0                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  PHASE 1: INPUTS (AskUserQuestion)                          │
│  ├── Content path(s).............. [/path/to/content]       │
│  ├── Logo path.................... [/path/to/logo.png]      │
│  ├── Founder photos............... [/path/to/photos/*]      │
│  ├── Slide framework.............. [FAU Runway 11]          │
│  └── Website URL (for colors)..... [https://company.com]    │
│                                                             │
│  PHASE 2: EXTRACTION (Automated)                            │
│  ├── Auto-discover content......... ✓                       │
│  ├── Extract brand colors.......... ✓                       │
│  ├── Map content to slides......... ✓                       │
│  └── Generate design-theme-sheet... ✓                       │
│                                                             │
│  PHASE 3: GENERATION (Automated)                            │
│  ├── Generate slide content........ ✓                       │
│  ├── Create PPTX draft............ ✓                        │
│  └── Generate thumbnails.......... ✓                        │
│                                                             │
│  PHASE 4: EDIT LOOP (Interactive)                           │
│  ├── Slide 1/11: Vision........... [Edit] [Approve]         │
│  ├── Slide 2/11: Team............. [Edit] [Approve]         │
│  ├── ...                                                    │
│  └── [< Prev] [Next >] [Jump to #] [Approve All]            │
│                                                             │
│  PHASE 5: EXPORT (Final)                                    │
│  ├── Final approval checkbox...... [ ] Approved             │
│  └── Export PPTX.................. [Generate Final]         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Consequences

Positive

Better UX: Structured questions reduce ambiguity
Automation: Color extraction saves manual work
Quality: Edit loop ensures review before export
Flexibility: Multiple frameworks (FAU, YC, custom)
Traceability: State tracking for edit history

Negative

Complexity: More code to maintain
Dependencies: WebFetch for color extraction may fail on some sites
Time: Interactive workflow takes longer than direct generation

Mitigations

Fallback to default colors if extraction fails
Skip edit loop option for experienced users
Cache extracted colors for reuse

Implementation Plan

Phase	Description	Files	Estimated Effort
A	Input collection + color extraction	color-extractor.js, themes/*.yaml	Medium
B	Content auto-discovery + mapping	content-scanner.py, templates/*.json	Medium
C	Slide-by-slide edit loop	edit-loop-state.json, SKILL.md updates	High
D	Final approval workflow	SKILL.md completion section	Low
E	Web-based Pitch Deck Studio	studio/* (Next.js app, Docker, Cloud Run)	High

Phase E Implementation Status

Component	Status	Notes
package.json	✅ Complete	Next.js 14, Zustand, PptxGenJS, Tailwind
tailwind.config.ts	✅ Complete	Dark theme, GxP LIMS-inspired
deck-store.ts	✅ Complete	Zustand state with persist, slide management
page.tsx	✅ Complete	3-panel layout
wizard-panel.tsx	✅ Complete	Step navigation container
welcome-step.tsx	✅ Complete	Features overview
framework-step.tsx	✅ Complete	4 framework options
company-step.tsx	✅ Complete	Company info form
colors-step.tsx	✅ Complete	Color picker + presets
team-step.tsx	✅ Complete	Dynamic founder list
contact-step.tsx	✅ Complete	Contact info form
footer-step.tsx	✅ Complete	Footer options
content-step.tsx	✅ Complete	Content ingestion with auto-discovery
editor-step.tsx	✅ Complete	Slide-by-slide editor with approval
review-step.tsx	✅ Complete	Deck review with thumbnail grid
export-step.tsx	✅ Complete	Multi-format export with download
preview-panel.tsx	✅ Complete	Live preview with step-aware rendering
Dockerfile	✅ Complete	Multi-stage build for Cloud Run
Dockerfile.dev	✅ Complete	Development with hot-reload
docker-compose.yml	✅ Complete	Local development
cloudbuild.yaml	✅ Complete	GCP CI/CD with verification
api/health/route.ts	✅ Complete	Health check endpoint

References

ADR-139: Skill Standard Enhancement (if exists)
PPTX Skill: .claude/skills/pptx/SKILL.md
html2pptx.md: .claude/skills/pptx/html2pptx.md
Current pitch-deck-mastery: .claude/skills/pitch-deck-mastery/SKILL.md

Decision Record

Decision Date: 2026-01-29
Decision Maker: Hal Casteel
Implementing Agent: Claude (Opus 4.5)
Track: F (Documentation)
Task ID: F.1.1

Compliance: CODITECT ADR Standard v1.0.0

Status​

Context​

Decision​

Phase A: Enhanced Input Collection + Color Extraction​

Phase B: Content Auto-Discovery + Mapping​

Phase C: Slide-by-Slide Edit Loop​

Phase D: Final Approval Workflow​

Phase E: Web-Based Pitch Deck Studio​

Architecture​

File Structure​

Workflow Diagram​

Consequences​

Positive​

Negative​

Mitigations​

Implementation Plan​

Phase E Implementation Status​

References​

Decision Record​