Electrum — Product Definition Toolkit for Software-Augmented Hardware

The Problem

Software PMs have established tools — user stories, PRDs, sprint planning. Pure hardware PMs have theirs — datasheets, BOMs, DFM checklists. But when the product is both — firmware-driven hardware with sensors, actuators, maybe an app, maybe cloud — most PMs either use a software PRD template that ignores physics, or a hardware spec that ignores the software.

The boundary between HW and SW is where the expensive mistakes happen, and it's usually the least documented part.

Quickstart for PMs and Product Strategists

You have a connected product idea and want to stress-test it before committing resources. Here's the fastest path:

# 1. Install Claude Code (https://docs.anthropic.com/en/docs/claude-code)
# 2. Clone this repo and open a terminal in it
git clone https://github.com/yoelf22/electrum.git && cd electrum

# 3. Start Claude Code and run the skill
claude
> /electrum <describe your product in one sentence>

The process will walk you through a structured dialogue — mapping the HW/SW boundary, forcing specifics, and surfacing what you're still assuming. It pauses after every output for your review. Budget 60–90 minutes for a full run.

Don't have Claude Code? The templates work without AI. Copy templates/system_description_template.md into your project folder, fill it in by hand, then run through templates/checklist.md. That's 80% of the value.

Want to see what a full run looks like? Read the Bubbler walkthrough — a soup-to-nuts example that turned "automated soap bubble machine" into a force-sensing feedback system with a 90-item gate review.

---

What This Toolkit Does

A repeatable, AI-assisted process for defining hardware products that have software inside them — so the firmware team and the mechanical team aren't surprised by each other at EVT.

It takes a product idea from "I think this could work" through to a structured system description, product illustrations, and a presentation-ready carousel. Eight phases, driven by the /electrum Claude Code skill:

| Phase | Output | Description | |-------|--------|-------------| | 1. Explore | explore_notes.md | Map the HW/SW boundary, identify knowledge gaps, surface risks | | 2. High-Level Design | high_level_design.md | Single-page system overview: blocks, interfaces, constraints, hardest problems | | 3. System Description | system_description.md | Full engineering-grade spec with real components, power budgets, firmware architecture | | 4. Gate Checklist | gate_checklist.md | Validate completeness across both domains (90 items, PASS/FAIL/N/A) | | 5. Image Generation | cross_section_illustration_*.png | Product illustrations via ChatGPT DALL-E (browser automation) | | 6. PPTX Carousel | *_Carousel.pptx | LinkedIn-format slide deck (4:5 portrait, dark theme, 8 pages) | | 7. PDF Carousel | *_Carousel.pdf | Same carousel as multi-page PDF |

Phases 1-4 produce the engineering definition. Phases 5-7 turn it into visual presentation materials.

Prerequisites

Python dependencies

pip install -r requirements.txt

Required packages: python-pptx, reportlab, playwright, matplotlib, numpy.

Playwright browser (for image generation)

pip install playwright
python -m playwright install chromium

Claude Code (for the /electrum skill)

Install Claude Code and open a terminal in this repo. The /electrum skill is automatically available:

claude
> /electrum smart posture-correcting office chair

Repository Structure

├── scripts/          # Python reference implementations (carousel, diagrams, deck builders)
├── templates/        # Directive markdown files (workflow, checklists, templates)
├── examples/         # Worked examples with full output artifacts
│   ├── bubbler-automated-soap-bubble-maker/   ← start here (has WALKTHROUGH.md)
│   ├── pop-miniature-popcorn-machine/
│   ├── metronome/
│   ├── chair_balancing_act/
│   ├── consumable-electric-toothbrush/
│   ├── shusher/
│   └── smart_sensor_hub/
└── output/           # Raw output from recent runs

What's in the Box

Templates and Checklists

| File | What it does | |------|-------------| | electrum/templates/hw_sw_product_initiation.md | 7-phase workflow from concept to presentation | | electrum/templates/hw_sw_high_level.md | Single-page system overview template | | electrum/templates/system_description_template.md | Full system description template with HW↔SW boundary items | | electrum/templates/checklist.md | Gate checklist — 90 items, each tagged if it targets the HW/SW boundary | | electrum/templates/skills_map.md | 16 competency areas a PM should understand or staff for | | .claude/skills/electrum/SKILL.md | Claude Code skill definition (drives the 7-phase workflow) |

Reference Scripts

| File | What it does | |------|-------------| | electrum/scripts/generate_illustration.py | DALL-E image generation via Playwright browser automation | | electrum/scripts/build_carousel.py | PPTX + PDF carousel builder (LinkedIn-format, 4:5 portrait) | | electrum/scripts/build_deck.py | Executive product overview deck builder | | electrum/scripts/build_high_level_deck.py | High-level design deck builder | | electrum/scripts/visualize.py | Visualization utilities | | electrum/scripts/block_diagram.py | Block diagram generator |

Worked Examples

| Project | What it is | Phases covered | |---------|-----------|----------------| | bubbler-automated-soap-bubble-maker/ | Force-sensing automated bubble machine with adaptive optimization — full walkthrough | All 8 phases | | pop-miniature-popcorn-machine/ | Miniature countertop popcorn machine with heating and motor control | Explore, HLD, system description, gate checklist, carousel | | metronome/ | Wrist-worn haptic metronome bracelet for musicians — silent, precise beat pulses | All phases | | chair_balancing_act/ | Clip-on tilt sensor that plays an escalating tone when a chair leaves static balance | HLD, system description, gate checklist | | consumable-electric-toothbrush/ | Disposable electric toothbrush with wear tracking | Full | | shusher/ | Noise-aware mechanical mute device with sound detection | HLD, system description, gate checklist | | smart_sensor_hub/ | Wireless indoor environment monitor (CO2, temp, humidity, PM) with BLE mesh | HLD, system description |

The bubbler example includes a step-by-step walkthrough showing what each phase surfaced and what the team would have missed without the process.

How to Use

With Claude Code (recommended)

1. Open a terminal in this repo
2. Run claude to start Claude Code
3. Type /electrum <your product idea>
4. Walk through all 8 phases interactively — Claude drafts, you review and refine at each step
5. Final output: a complete product definition + diagrams + presentation deck

Without Claude Code

The core toolkit is markdown templates and checklists — no AI required:

1. Understand the process — Read electrum/templates/hw_sw_product_initiation.md for the workflow overview
2. Assess your gaps — Review electrum/templates/skills_map.md for team competency planning
3. Create the high-level design — Copy electrum/templates/hw_sw_high_level.md into your project folder and fill it in
4. Write the system description — Copy electrum/templates/system_description_template.md and work through each section
5. Validate — Run through electrum/templates/checklist.md to confirm nothing was missed

For image generation and carousel building, adapt the scripts in electrum/scripts/ to your product.

Who This is For

Hardware product managers and technical leads building products where physical hardware and software must be designed together. The toolkit is most useful when:

• Your product has firmware, and maybe a companion app or cloud backend
• Your team spans EE/ME and software disciplines
• You need documents that both an executive and an engineer can use
• You want presentation-ready materials alongside the engineering spec
• You've been burned before by HW/SW integration surprises at EVT