2. Roadmap Generation
Outcome: Professional AI Roadmap PDF demonstrating deep business understanding with specific ROI projections Trigger: Discovery Call complete (all interviews finished, transcripts saved) Duration: 1-2 hours (generation + review) Output: {client}/AI-ROADMAP.md and {client}/AI-ROADMAP.pdf
Quick Reference
1
Verify inputs complete
5 min
Manual check
2
Run roadmap pipeline
20-40 min
./scripts/roadmap.sh {client}
3
Review & refine output
30-45 min
Manual review
4
Prepare for delivery
5 min
PDF conversion
Total: ~1-2 hours
Prerequisites
Before starting, verify:
Step 1: Verify Inputs (5 min)
Check that your transcripts include sufficient data:
Business Context
What they do, team size, why automation now
Software Stack
At least 3-5 tools mentioned
Processes
At least 3 processes/tasks with step-by-step walkthroughs
Pain Points
Quantification (time, frequency, impact) for major processes
ROI Data
Hours per week + hourly rates for key roles
Goals
Growth/future state discussed
If data is thin: Fill gaps from recordings or ask client via email before proceeding. Having multiple call transcripts (onboarding + interviews) gives the generator much richer data to work with than a single call ever could.
Step 2: Run the Roadmap Pipeline (20-40 min)
Primary method (recommended):
By 4-letter client code:
Enterprise roadmap (custom software, investment tables):
Autonomous mode (skip review gate, auto-approve):
The pipeline runs 7 phases, each spawning a fresh agent:
0
Pre-Flight
Validates client folder, finds transcripts, checks API keys
5-10s
1
Transcript Analysis
Extracts team, pain points, quotes, hours, software stack
3-5 min
2
Platform Research
Researches each platform's API, industry context, compliance
5-10 min
3
Document Generation
Writes complete AI-ROADMAP.md using template and exemplars
5-10 min
4
Mac Review
Human gate -- approve, edit, or skip PDF
Manual
5
Diagrams
Generates workflow diagram PNGs via Gemini
1-2 min
6
Generates branded PDF via WeasyPrint
10-30s
Phase 4 pauses for your review in interactive mode. In autonomous mode, it auto-approves. Resume after failure: completed phases are auto-skipped on re-run.
Step 3: Review & Refine (30-45 min)
Open generated {client}/AI-ROADMAP.md and verify:
Quality Checklist (18 items)
1
Executive summary
Has the total savings number in the first paragraph (not vague)
2
Team table
Every person from the transcripts appears with name, role, hours, and cost
3
Software ecosystem table
All platforms listed with 7+ columns (Platform, API Type, Auth, Rate Limits, n8n Integration, Key Endpoints, Docs)
4
Client quotes
Direct quotes from call transcripts woven into the narrative
5
ROI math
Hours x rate x 52 = annual cost. Automation savings realistic (60-90%, not 100%)
6
Automation opportunities
Each has description, current state, automated state, time savings, annual value
7
Org chart section
"How Your Team Operates" with narrative about manual vs strategic time
8
Opportunity matrix
"Where to Start" with recommended positions explained
9
Workflow cards
Each opportunity has "How It Works" card with 4-6 bullets + savings headline
10
12-month timeline
Month-by-month table with future-state narrative
11
Deep API research
Platforms without APIs note Kernel.sh as fallback
12
Image branding
All generated PNGs use TEAI branding (navy, blue accents, green for money)
13
Compliance section
Industry-specific considerations if relevant
14
300+ lines
Shorter usually means missing depth -- expand thin sections
15
Research Sources
Includes real URLs from web research, not placeholders
16
One-Time Optimisations
3-5 items connected to automation readiness
17
Assessed but Not Recommended
2-3 items with honest reasons (builds trust)
18
Common Questions
At least 5 Q&A pairs present
Common Fixes
Generic language ("your team")
Replace with specific names from the calls ("Maddy", "the warehouse team")
Over-optimistic ROI
Cap automation efficiency at 85-90%. Some human oversight always remains
Missing limitations
Add "What It Cannot Do" for each opportunity -- builds trust
Jargon (API, webhook, endpoint)
Replace with client-friendly language ("automatic connection", "trigger")
Fabricated quotes
Cross-check every blockquote against transcripts. Remove unverified quotes
ROI math errors
Check: hours/week x rate x 52. Conservative estimate should be 75% of calculated savings
Missing platforms
Search all transcripts for tool names. Verify each appears in the ecosystem table
Wrong timeline estimates
Default ~6 weeks per workflow. LOW ~4wk, HIGH ~8-12wk only. Max 2 concurrent
Step 4: Prepare for Delivery (5 min)
Convert roadmap to PDF (the client receives this, not the markdown)
Filename:
{Company Name} - AI Roadmap.pdfSave to
{client}/context/docs/AI-Roadmap-{DATE}.pdfDo not send directly to client -- hand off to sales (see Roadmap Presentation)
Edge Cases
Regulated Industries (Healthcare, Finance, Legal)
The agent automatically adds a compliance section when keywords are detected:
Healthcare: HIPAA
Finance: SOC2, PCI-DSS
Legal: Attorney-client privilege
Verify: Correct regulations identified, automation opportunities don't violate compliance, appropriate caveats included.
Legacy Systems
Verify: Workarounds are realistic, ROI accounts for additional integration effort, automation % is adjusted appropriately.
Multi-Location/Multi-Team Clients
May need separate opportunity sections per location
ROI should aggregate across locations
Note implementation phasing by location
Feasibility Check
For any capability that is:
Novel (we haven't built this exact thing before)
Dependent on third-party constraints (API limits, platform ToS)
High-value ($5K+ or critical to client's decision)
Required: Build a POC or spike before including in roadmap.
Red Flags Requiring POCs
Scraping websites with bot detection
AI content that must pass plagiarism checks
Real-time integrations with rate-limited APIs
Automations bypassing platform intended workflows
Any "we think we can do this" statements
If uncertain: Mark as "Exploratory" with disclaimer:
"This capability requires technical validation. We'll confirm feasibility during the first week of development before committing budget."
Document Turnaround
Simple (1-2 workflows)
Same day
Standard (3-4 workflows)
Same day
Complex (5+ workflows)
Next business day
Troubleshooting
"No transcript files found"
Rename transcript file to include "call" or "interview" in the filename
Phase 1 fails with thin data
Transcript too short or lacks specific numbers. Re-listen to calls, add manual notes with hours/rates
Phase 2 timeout
Too many platforms, web search taking too long. Re-run -- the script resumes from Phase 2 automatically
Phase 3 produces short doc
Check the state file at planning/_roadmap_state.json -- are phase data fields populated?
ROI numbers seem wrong
Check arithmetic: hours/week x rate x 52. Conservative estimate should be 75% of calculated savings
Fabricated quotes
Cross-check every blockquote against the transcript. Remove any that can't be verified
Diagram generation fails
GOOGLE_API_KEY not set or quota exceeded. Non-blocking -- PDF generates without diagrams
PDF generation fails
Install: pip install weasyprint markdown
State file corrupted
Delete planning/_roadmap_state.json and re-run from scratch
Verify
Before marking complete:
Next: Roadmap Presentation
Last updated