Stakeholder Document Generator

Transform technical architecture blueprints into presentation-ready documents for executive presentations, budget approvals, and stakeholder buy-in.

Perfect for: CTO reviews, board presentations, finance approvals, agency RFPs, investor updates

When to Use This Skill

Use this skill when you need to:

• •Present architecture to non-technical stakeholders (executives, product managers, business teams)
• •Get budget approval for development costs
• •Share technical decisions with wider team before proceeding
• •Create RFPs for agency vendors
• •Document architectural decisions for compliance/audit

Input: Full architecture blueprint (from /architect:blueprint) Output: Word document (.docx) with diagrams rendered as PNGs

Document Structure

1. Cover Page

# [Project Name]
## Architecture & Implementation Plan

**Prepared for**: [Stakeholder Name/Team]
**Prepared by**: Architect AI
**Date**: [Today's Date]
**Version**: 1.0

2. Executive Summary (1 page max)

Translate technical blueprint into business value:

## Executive Summary

**What we're building**: [One-sentence description from blueprint]

**Who it's for**: [Customer type from requirements - B2B enterprise/SMB/B2C]

**Business Value**:
- [Extract from blueprint: What problem does this solve?]
- [Key capability that drives value]
- [Integration or feature that reduces friction]

**Timeline**:
- MVP (core features): [Calculate from sprint backlog - usually 8 weeks]
- Production-ready: [Add 4 weeks for enterprise features if B2B]

**Budget**:
- Infrastructure: $[Low]-[High]/month (from cost estimate section)
- Development: $[Low]-[High] (from Next Steps - 3 build paths)

**Major Risks** (top 3):
1. [Extract from Complexity Assessment - highest-scored complexity factors]
   - **Mitigation**: [From blueprint's risk mitigation notes]
2. [Second highest risk]
   - **Mitigation**: [Strategy]
3. [Third risk]
   - **Mitigation**: [Strategy]

**Recommendation**: GO - Architecture is sound, risks are manageable, timeline is realistic.
[Or: PROCEED WITH CAUTION if complexity score > 7/10]

Rules:

• •Use non-technical language (translate JWT → "secure login tokens", RLS → "data isolation", etc.)
• •Lead with business impact, not technical features
• •Keep to 1 page maximum
• •Include confidence level in recommendation (High/Medium/Low based on complexity score)

3. Solution Overview

3.1 High-Level Architecture Diagram

Extract from blueprint's Architecture Diagram section:

• •Take the C4 Container diagram (Mermaid code)
• •Render to PNG (1200px width minimum)
• •Caption: "System components and how they connect"

Simplify for non-technical audience:

• •Frontend → "User Interface (Web/Mobile)"
• •Backend → "Business Logic Server"
• •Database → "Data Storage"
• •Keep external integrations (Stripe, Slack, etc.) - business stakeholders recognize these

3.2 Solution Components Table

Extract from blueprint and present as table:

3.3 Key Capabilities Checklist

Extract from blueprint's Plain English Specifications:

• •✅ [Feature 1 from specs]
• •✅ [Feature 2 from specs]
• •✅ [Feature 3 from specs]
• •✅ [Critical integration]
• •✅ [Security/compliance feature if mentioned]

Limit to top 6 capabilities that stakeholders care about.

4. Technology Stack & Decisions

For each major technology decision, create a decision card:

Extract from:

• •Database Schema section → Database choice
• •Architecture Diagram → Hosting choice
• •Application Architecture section → Architecture pattern
• •Product Type Detection → Multi-tenancy approach (if B2B)

Template for Each Decision:

### Decision: [Technology Category] - [Choice] ✅ Recommended

**Why [Choice]?**
- ✅ [Business benefit 1 - extract from blueprint's tech stack reasoning]
- ✅ [Business benefit 2]
- ✅ [Cost or hiring benefit]
- ✅ [Proven track record - if mentioned in blueprint]

**Alternatives Considered**:
- ❌ [Alternative 1]: [Why rejected - from blueprint's ADRs or alternatives]
- ❌ [Alternative 2]: [Why rejected]

**Upgrade Path**: [From blueprint's assumptions - "Start with X, upgrade to Y when Z"]

**Risk**: [Low/Medium/High based on blueprint's complexity assessment]

Example (using blueprint data):

### Decision: Database - PostgreSQL ✅ Recommended

**Why PostgreSQL?**
- ✅ Handles relational data (tickets, users, workspaces) efficiently
- ✅ Used by Instagram, Notion, Figma - proven at scale
- ✅ $0-25/month free tier, scales to millions of users
- ✅ Built-in multi-tenancy support (Row-Level Security)

**Alternatives Considered**:
- ❌ MongoDB: Doesn't fit relational data model, harder data integrity
- ❌ MySQL: Less feature-rich, weaker JSON support

**Upgrade Path**: Start with Supabase free tier → Upgrade to Pro ($25/month) at 1K users

**Risk**: Low - Industry standard with massive community support

Generate decision cards for:

1. •Database
2. •Hosting (managed platforms vs AWS/GCP)
3. •Architecture pattern (monolith vs microservices)
4. •Multi-tenancy approach (if B2B product detected)

Add ⚠️ "Requires Validation" flag if:

• •Complexity score for this decision > 6/10
• •Blueprint mentions "needs validation" or "confirm with user"
• •Security-critical decision (e.g., multi-tenant data isolation)

5. Cost Breakdown

Extract from blueprint's Cost Estimate section.

5.1 Infrastructure Costs (monthly recurring)

Create 3 scenarios from blueprint:

Breakdown (Growth scenario): [List each service from cost estimate with monthly cost]

5.2 Development Costs (one-time)

Extract from blueprint's Next Steps Guide (3 build paths):

5.3 Total First-Year Cost

Calculate:

Development: $[Choose middle path - hire developer]
Infrastructure: $[Growth tier × 12]
Third-party: $[Domain + other one-time costs]
Total Year 1: $[Sum]

6. Major Architectural Decisions & Defense

Q&A format for common stakeholder questions:

Extract from blueprint and translate to Q&A:

Q: Why not use AWS instead of [recommended hosting]?

A: [Extract from blueprint's hosting decision reasoning, translate to business terms]

Example:

AWS requires a DevOps engineer ($120K/year salary). Managed platforms (Vercel + Supabase) handle deployment, scaling, and backups automatically for $1,800/year. We save $118K/year and ship 3-5x faster.

When to switch: When you reach >100K users or need enterprise compliance (SOC 2), estimated 12-18 months away.

Q: Why monolith instead of microservices?

A: [Extract from blueprint's architecture pattern decision]

Q: How do we prevent [top security concern from blueprint]?

A: [Extract security mitigations from Security Architecture section]

Rules:

• •Lead with business impact ($$ savings, time savings, risk reduction)
• •Include "When to switch" for each decision (upgrade path)
• •Keep answers to 2-3 sentences max

7. Risk Assessment

Extract from blueprint's Complexity Assessment and Well-Architected Review.

Create risk table:

Severity calculation:

• •High: Complexity score 7-10/10
• •Medium: Complexity score 4-6/10
• •Low: Complexity score 1-3/10

Probability:

• •Extract from blueprint's risk flags or assume:
  • •High: New/unproven technology
  • •Medium: Standard technology, some complexity
  • •Low: Proven patterns, low complexity

Add these standard risks:

• •Vendor lock-in: Low severity, High probability → Mitigation: Exit strategy documented
• •Budget overrun: Medium severity, Low probability → Mitigation: Fixed-price contracts + monthly caps
• •Timeline slippage: Medium severity, Medium probability → Mitigation: Risk-prioritized sprints

8. Timeline & Milestones

Extract from blueprint's Sprint Backlog section.

Convert sprints to milestone table:

Highlight critical path:

Critical Path: [Identify hardest/riskiest sprints from backlog] - any delay here impacts launch

9. Success Metrics

Extract from blueprint's Service Level Objectives and Next Steps.

MVP Success (Week [calculated from sprint backlog]):

• •✅ [From SLO section: availability target]
• •✅ [From SLO section: latency target]
• •✅ [User count target from scale assumptions]
• •✅ Infrastructure costs < $[from cost estimate]

Production Success (Week [MVP + 4]):

• •✅ First paying customer onboarded
• •✅ [From SLO: uptime achieved]
• •✅ [From SLO: performance target]
• •✅ Security audit completed (if mentioned in security section)

Business Success (6 months):

• •[Infer based on product type and scale]:
  • •B2B SaaS: 100+ paying customers, $10K+ MRR
  • •B2C: 10K+ active users, <5% churn
  • •Marketplace: $100K+ GMV

10. Next Steps & Approval Checklist

Immediate Actions (if approved):

Extract from blueprint's Next Steps Guide:

• • Week 1: Run /architect:scaffold to bootstrap repos
• • Week 1: Setup accounts [list from Required Accounts section]
• • Week 1: Configure CI/CD pipeline
• • Week 1-2: [Hire developers if external team]
• • Week 2: Sprint 0 complete (can deploy to production)

Approval Checklist:

• • Budget approved: $[Development cost] + $[Infrastructure/month]
• • Timeline approved: [Weeks to MVP]
• • Major tech decisions approved: [Database, hosting, architecture pattern]
• • Risk mitigation approved: [Top 3 risks from risk table]
• • Success metrics agreed: [From Success Metrics section]

Decision Required By: [Today + 2 weeks]

Approved By: ___________________________ Date: ___________

11. Appendices

A. Glossary

Auto-generate from technical terms used in document:

• •API: How software components talk to each other
• •Backend: Server-side code that processes data
• •Database: Where all data is stored
• •Frontend: User interface in the browser
• •Monolith: Single application (vs many small services)
• •Multi-tenant: Multiple customers share infrastructure, data isolated
• •PostgreSQL: Database used by Instagram, Notion, Figma
• •Row-Level Security (RLS): Database security that isolates customer data
• •SaaS: Software accessed via web browser
• •SSO: Login with company credentials

Rule: Only include terms actually used in the document.

B. Technical Diagrams (as PNGs)

Render these diagrams from blueprint as PNG:

1. •Architecture diagram (C4 Container)
2. •Database schema (ERD) - if included in blueprint
3. •User flow diagrams - if included
4. •Deployment diagram - if included

Minimum width: 1200px for clarity

C. Reference Links

• •Full architecture blueprint (link to markdown file)
• •Sprint backlog (link to detailed user stories)
• •Cost calculator (link if interactive spreadsheet exists)

Document Formatting

Output as Markdown (can be converted to .docx):

# [Project Name]
## Architecture & Implementation Plan

---

## Executive Summary
[Content...]

---

## Solution Overview
[Content...]

![Architecture Diagram](./diagrams/architecture.png)
*System components and how they connect*

---

[Continue with all 11 sections...]

Style Guidelines:

• •Use ## for main sections (Executive Summary, Solution Overview, etc.)
• •Use ### for subsections
• •Use tables for structured data (costs, components, risks, timeline)
• •Use ✅ for success criteria and capabilities
• •Use ❌ for alternatives rejected
• •Use ⚠️ for requires validation
• •Use bold for emphasis on business-critical points
• •Use code only for actual technical terms that need monospace

Output Format

When invoked, generate:

📄 Generating stakeholder document...

✅ Extracted executive summary from blueprint
✅ Rendered architecture diagram to PNG (1200x800)
✅ Compiled tech stack decisions (4 decisions)
✅ Calculated cost breakdown (3 scenarios)
✅ Generated risk assessment (6 risks)
✅ Created timeline from sprint backlog (8 sprints, 12 weeks total)
✅ Added approval checklist

📄 stakeholder-presentation.md created (11 sections, 2,847 words)
📁 diagrams/ folder created with 1 PNG

Ready to share with stakeholders!

Next steps:
- Convert to .docx: Use Pandoc or copy into Word
- Review and customize for your stakeholder audience
- Add company logo to cover page
- Update "Decision Required By" date

Customization Options

Optional parameters (ask user if they want to customize):

1. •Stakeholder name/title: "CTO Review Committee", "Board of Directors", etc.
2. •Budget constraints: Max budget to flag in recommendations
3. •Timeline constraints: Must-launch-by date to compare against
4. •Company logo: Upload for cover page
5. •Custom branding: Color scheme, fonts

Default behavior: Generate with standard formatting if no customization requested.

Success Criteria

A good stakeholder document should:

• •✅ Be understandable by non-technical executives
• •✅ Articulate business value (not just technical features)
• •✅ Include realistic timelines and costs (not optimistic best-case)
• •✅ Address risks upfront with mitigation strategies
• •✅ Provide clear recommendation (Go/No-Go with confidence)
• •✅ Include approval checklist for decision-making
• •✅ Use visual diagrams (PNGs, not Mermaid text)
• •✅ Defend technical decisions with business justification

Error Handling

If blueprint is incomplete:

• •Missing cost estimate → Use defaults ($50-150/month infrastructure)
• •Missing sprint backlog → Estimate 8-12 weeks for MVP
• •Missing complexity assessment → Mark all risks as "Medium"
• •Missing SLOs → Use industry standards (99.9% uptime, <500ms latency)

If blueprint is from /architect:quick-spec:

• •Warn user: "Quick-spec doesn't have enough detail. Run /architect:blueprint first."

Examples

See STAKEHOLDER_DOC_SPEC.md for detailed examples of each section.