stakeholder-doc

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:

Component	Technology	Purpose	Cost/Month
[From manifest: frontend]	[Framework]	User interface	$[From cost estimate]
[From manifest: backend]	[Framework]	Business logic	$[From cost estimate]
[From manifest: database]	[Type]	Data storage	$[From cost estimate]
[From manifest: integrations]	[Services]	[Purpose]	$[From cost estimate]
Total			$[Sum]/month

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:

Scenario	User Count	Cost/Month	Cost/Year	Notes
MVP	[From blueprint scale assumptions]	$[Low]	$[Low × 12]	Free tiers sufficient
Growth	[10x MVP]	$[Mid]	$[Mid × 12]	Paid tiers + scaling
Scale	[100x MVP]	$[High]	$[High × 12]	Enterprise tiers

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):

Path	Cost	Timeline	Best For
Build with AI tools	$[From Next Steps]	[Weeks]	Technical founders
Hire developer	$[From Next Steps]	[Weeks]	Budget $20K-50K
Hire agency	$[From Next Steps]	[Weeks]	Enterprise projects

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:

Risk	Severity	Probability	Mitigation	Owner
[Top complexity factor]	High/Med/Low	High/Med/Low	[From blueprint's mitigation notes]	Dev Team/CTO
[Second factor]	...	...	...	...
[Third factor]	...	...	...	...

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:

Phase	Duration	Deliverables	Success Criteria
Sprint 0: Setup	1 week	[From sprint 0 goals]	✅ [From acceptance criteria]
Sprint 1: [Feature]	[Duration]	[From sprint goals]	✅ [From acceptance criteria]
Sprint 2: [Feature]	[Duration]	[From sprint goals]	✅ [From acceptance criteria]
...	...	...	...
MVP Launch	[Total weeks]	All core features	✅ [From sprint backlog MVP definition]
Production	[Total + 4 weeks]	Enterprise-ready	✅ First paying customer

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.