# 2. Roadmap Generation **Outcome:** Professional AI Roadmap PDF demonstrating deep business understanding with specific ROI projections **Trigger:** [Discovery Call](https://internal-docs.theentourageai.com/ai-roadmap/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 | Step | Action | Time | Method | | ---- | ---------------------- | --------- | ------------------------------- | | 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: * [ ] [Discovery Call](https://internal-docs.theentourageai.com/ai-roadmap/discovery-call) completed (onboarding call + all staff interviews) * [ ] All call transcripts saved to `{client}/context/calls/` * [ ] CLIENT.md updated with complete data from all calls (team, pain points, processes, tech stack) * [ ] Client code assigned (e.g., NADD, CRFG) * [ ] (Optional) `GOOGLE_API_KEY` or `GEMINI_API_KEY` set for diagram generation * [ ] (Optional) `weasyprint` installed for PDF generation (`pip install weasyprint markdown`) *** ### Step 1: Verify Inputs (5 min) Check that your transcripts include sufficient data: | Data Point | Minimum Content | | ---------------- | ------------------------------------------------------------ | | 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):** ```bash ./scripts/roadmap.sh {client} ``` **By 4-letter client code:** ```bash ./scripts/roadmap.sh NADD ``` **Enterprise roadmap (custom software, investment tables):** ```bash ./scripts/roadmap.sh {client} --enterprise ``` **Autonomous mode (skip review gate, auto-approve):** ```bash ./scripts/roadmap.sh {client} --mode=autonomous ``` The pipeline runs 7 phases, each spawning a fresh agent: | Phase | Name | What Happens | Duration | | ----- | ------------------- | ------------------------------------------------------------ | -------- | | 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 | PDF | 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) | # | Check | What to Look For | | -- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 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 | Issue | Fix | | ------------------------------- | ---------------------------------------------------------------------------------------- | | 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) 1. Convert roadmap to PDF (the client receives this, not the markdown) 2. Filename: `{Company Name} - AI Roadmap.pdf` 3. Save to `{client}/context/docs/AI-Roadmap-{DATE}.pdf` 4. Do not send directly to client -- hand off to sales (see [Roadmap Presentation](https://internal-docs.theentourageai.com/ai-roadmap/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 | Complexity | Turnaround | | ------------------------ | ----------------- | | Simple (1-2 workflows) | Same day | | Standard (3-4 workflows) | Same day | | Complex (5+ workflows) | Next business day | *** ### Troubleshooting | Issue | Solution | | ---------------------------- | ------------------------------------------------------------------------------------------------------- | | "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: * [ ] `AI-ROADMAP.md` exists in `{client}/` * [ ] PDF exported to `{client}/context/docs/` * [ ] Document customized (no placeholder text) * [ ] All opportunities have specific annual ROI * [ ] At least one client quote included * [ ] Top recommendations align with their stated priorities * [ ] Quality checklist passed (18 items above) **Next:** [Roadmap Presentation](https://internal-docs.theentourageai.com/ai-roadmap/roadmap-presentation)