aidp 0.27.0 → 0.28.0

data/lib/aidp/planning/generators/marketing_report_generator.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require_relative "../../logger"
+
+module Aidp
+  module Planning
+    module Generators
+      # Generates marketing report with key messages and differentiators
+      # Uses AI to craft compelling narratives from technical features
+      # Follows Zero Framework Cognition (ZFC) pattern
+      class MarketingReportGenerator
+        def initialize(ai_decision_engine:, config: nil)
+          @ai_decision_engine = ai_decision_engine
+          @config = config || Aidp::Config.agile_config
+        end
+
+        # Generate marketing report from MVP scope and feedback
+        # @param mvp_scope [Hash] MVP scope definition
+        # @param feedback_analysis [Hash] User feedback analysis (optional)
+        # @return [Hash] Marketing report structure
+        def generate(mvp_scope:, feedback_analysis: nil)
+          Aidp.log_debug("marketing_report_generator", "generate",
+            feature_count: mvp_scope[:mvp_features]&.size || 0,
+            has_feedback: !feedback_analysis.nil?)
+
+          # Use AI to generate marketing materials
+          marketing_report = generate_marketing_with_ai(mvp_scope, feedback_analysis)
+
+          {
+            overview: marketing_report[:overview],
+            value_proposition: marketing_report[:value_proposition],
+            key_messages: marketing_report[:key_messages],
+            differentiators: marketing_report[:differentiators],
+            target_audience: marketing_report[:target_audience],
+            positioning: marketing_report[:positioning],
+            success_metrics: marketing_report[:success_metrics],
+            launch_checklist: marketing_report[:launch_checklist],
+            messaging_framework: marketing_report[:messaging_framework],
+            metadata: {
+              generated_at: Time.now.iso8601,
+              key_message_count: marketing_report[:key_messages]&.size || 0,
+              differentiator_count: marketing_report[:differentiators]&.size || 0
+            }
+          }
+        end
+
+        # Format marketing report as markdown
+        # @param report [Hash] Marketing report structure
+        # @return [String] Markdown formatted marketing report
+        def format_as_markdown(report)
+          Aidp.log_debug("marketing_report_generator", "format_as_markdown")
+
+          output = ["# Marketing Report", ""]
+          output << "**Generated:** #{report[:metadata][:generated_at]}"
+          output << "**Key Messages:** #{report[:metadata][:key_message_count]}"
+          output << "**Differentiators:** #{report[:metadata][:differentiator_count]}"
+          output << ""
+
+          output << "## Overview"
+          output << ""
+          output << report[:overview]
+          output << ""
+
+          output << "## Value Proposition"
+          output << ""
+          output << "### Headline"
+          output << ""
+          output << report[:value_proposition][:headline]
+          output << ""
+          output << "### Subheadline"
+          output << ""
+          output << report[:value_proposition][:subheadline]
+          output << ""
+          output << "### Core Benefits"
+          output << ""
+          report[:value_proposition][:core_benefits].each do |benefit|
+            output << "- #{benefit}"
+          end
+          output << ""
+
+          output << "## Key Messages"
+          output << ""
+          report[:key_messages].each_with_index do |message, idx|
+            output << "### #{idx + 1}. #{message[:title]}"
+            output << ""
+            output << message[:description]
+            output << ""
+            output << "**Supporting Points:**"
+            message[:supporting_points].each do |point|
+              output << "- #{point}"
+            end
+            output << ""
+          end
+
+          output << "## Differentiators"
+          output << ""
+          output << "What sets us apart from competitors:"
+          output << ""
+          report[:differentiators].each_with_index do |diff, idx|
+            output << "### #{idx + 1}. #{diff[:title]}"
+            output << ""
+            output << diff[:description]
+            output << ""
+            output << "**Competitive Advantage:** #{diff[:advantage]}"
+            output << ""
+          end
+
+          output << "## Target Audience"
+          output << ""
+          report[:target_audience].each do |segment|
+            output << "### #{segment[:name]}"
+            output << ""
+            output << "**Description:** #{segment[:description]}"
+            output << ""
+            output << "**Pain Points:**"
+            segment[:pain_points].each do |pain|
+              output << "- #{pain}"
+            end
+            output << ""
+            output << "**Our Solution:**"
+            segment[:our_solution].each do |solution|
+              output << "- #{solution}"
+            end
+            output << ""
+          end
+
+          output << "## Positioning"
+          output << ""
+          output << "**Category:** #{report[:positioning][:category]}"
+          output << ""
+          output << "**Statement:** #{report[:positioning][:statement]}"
+          output << ""
+          output << "**Tagline:** #{report[:positioning][:tagline]}"
+          output << ""
+
+          output << "## Success Metrics"
+          output << ""
+          report[:success_metrics].each do |metric|
+            output << "- **#{metric[:name]}:** #{metric[:target]}"
+            output << "  - Measurement: #{metric[:measurement]}"
+            output << ""
+          end
+
+          output << "## Messaging Framework"
+          output << ""
+          output << "| Audience | Message | Channel | Call to Action |"
+          output << "|----------|---------|---------|----------------|"
+          report[:messaging_framework].each do |msg|
+            output << "| #{msg[:audience]} | #{msg[:message]} | #{msg[:channel]} | #{msg[:cta]} |"
+          end
+          output << ""
+
+          output << "## Launch Checklist"
+          output << ""
+          report[:launch_checklist].each_with_index do |item, idx|
+            output << "- [ ] **#{item[:task]}**"
+            output << "  - Owner: #{item[:owner]}"
+            output << "  - Timeline: #{item[:timeline]}"
+            output << ""
+          end
+
+          output.join("\n")
+        end
+
+        private
+
+        def generate_marketing_with_ai(mvp_scope, feedback_analysis)
+          Aidp.log_debug("marketing_report_generator", "generate_marketing_with_ai")
+
+          prompt = build_marketing_prompt(mvp_scope, feedback_analysis)
+
+          schema = {
+            type: "object",
+            properties: {
+              overview: {type: "string"},
+              value_proposition: {
+                type: "object",
+                properties: {
+                  headline: {type: "string"},
+                  subheadline: {type: "string"},
+                  core_benefits: {type: "array", items: {type: "string"}}
+                }
+              },
+              key_messages: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    title: {type: "string"},
+                    description: {type: "string"},
+                    supporting_points: {type: "array", items: {type: "string"}}
+                  }
+                }
+              },
+              differentiators: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    title: {type: "string"},
+                    description: {type: "string"},
+                    advantage: {type: "string"}
+                  }
+                }
+              },
+              target_audience: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: {type: "string"},
+                    description: {type: "string"},
+                    pain_points: {type: "array", items: {type: "string"}},
+                    our_solution: {type: "array", items: {type: "string"}}
+                  }
+                }
+              },
+              positioning: {
+                type: "object",
+                properties: {
+                  category: {type: "string"},
+                  statement: {type: "string"},
+                  tagline: {type: "string"}
+                }
+              },
+              success_metrics: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: {type: "string"},
+                    target: {type: "string"},
+                    measurement: {type: "string"}
+                  }
+                }
+              },
+              messaging_framework: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    audience: {type: "string"},
+                    message: {type: "string"},
+                    channel: {type: "string"},
+                    cta: {type: "string"}
+                  }
+                }
+              },
+              launch_checklist: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    task: {type: "string"},
+                    owner: {type: "string"},
+                    timeline: {type: "string"}
+                  }
+                }
+              }
+            },
+            required: ["overview", "value_proposition", "key_messages", "differentiators"]
+          }
+
+          decision = @ai_decision_engine.decide(
+            context: "marketing_report_generation",
+            prompt: prompt,
+            data: {
+              mvp_scope: mvp_scope,
+              feedback_analysis: feedback_analysis
+            },
+            schema: schema
+          )
+
+          Aidp.log_debug("marketing_report_generator", "ai_report_generated",
+            messages: decision[:key_messages]&.size || 0)
+
+          decision
+        end
+
+        def build_marketing_prompt(mvp_scope, feedback_analysis)
+          feedback_insights = if feedback_analysis
+            <<~INSIGHTS
+              USER FEEDBACK INSIGHTS:
+              #{feedback_analysis[:findings]&.map { |f| "- #{f}" }&.join("\n") || "No insights"}
+            INSIGHTS
+          else
+            ""
+          end
+
+          <<~PROMPT
+            Generate a comprehensive marketing report for the following MVP.
+
+            MVP FEATURES:
+            #{mvp_scope[:mvp_features]&.map { |f| "- #{f[:name]}: #{f[:description]}" }&.join("\n") || "No features"}
+
+            SUCCESS CRITERIA:
+            #{mvp_scope[:success_criteria]&.map { |c| "- #{c}" }&.join("\n") || "No criteria"}
+
+            #{feedback_insights}
+
+            TASK:
+            Create marketing materials that translate technical features into compelling value propositions:
+
+            1. OVERVIEW
+               - Brief summary of the marketing strategy
+
+            2. VALUE PROPOSITION
+               - Compelling headline (10-15 words)
+               - Supporting subheadline (15-25 words)
+               - 3-5 core benefits
+
+            3. KEY MESSAGES (3-5 messages)
+               - For each: title, description, 3-5 supporting points
+               - Focus on customer value, not technical features
+
+            4. DIFFERENTIATORS (2-4 items)
+               - What makes this unique?
+               - Competitive advantages
+               - Why choose us over alternatives?
+
+            5. TARGET AUDIENCE (2-3 segments)
+               - Name and description
+               - Pain points they experience
+               - How our solution addresses their needs
+
+            6. POSITIONING
+               - Category (what market/space are we in?)
+               - Positioning statement (who, what, value, differentiation)
+               - Tagline (memorable 3-7 words)
+
+            7. SUCCESS METRICS
+               - 4-6 measurable metrics for launch success
+               - Targets and how to measure
+
+            8. MESSAGING FRAMEWORK
+               - For each audience: specific message, channel, call to action
+
+            9. LAUNCH CHECKLIST
+               - 8-12 pre-launch tasks
+               - Owner and timeline for each
+
+            Make it compelling, customer-focused, and actionable. Avoid jargon.
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/aidp/planning/generators/mvp_scope_generator.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require_relative "../../logger"
+
+module Aidp
+  module Planning
+    module Generators
+      # Generates MVP scope definition using AI to analyze features
+      # Determines must-have vs nice-to-have features for MVP
+      # Uses Zero Framework Cognition (ZFC) - NO heuristics, pure AI decisions
+      class MVPScopeGenerator
+        def initialize(ai_decision_engine:, prompt: nil, config: nil)
+          @ai_decision_engine = ai_decision_engine
+          @prompt = prompt || TTY::Prompt.new
+          @config = config || Aidp::Config.agile_config
+        end
+
+        # Generate MVP scope from PRD and user priorities
+        # @param prd [Hash] Parsed PRD document
+        # @param user_priorities [Array<String>] User-specified priorities (optional)
+        # @return [Hash] MVP scope with must-have and nice-to-have features
+        def generate(prd:, user_priorities: nil)
+          Aidp.log_debug("mvp_scope_generator", "generate", has_prd: !prd.nil?)
+
+          # Collect user priorities if not provided
+          priorities = user_priorities || collect_user_priorities(prd)
+
+          Aidp.log_debug("mvp_scope_generator", "analyzing_features", priority_count: priorities.size)
+
+          # Use AI to analyze features and determine MVP viability
+          mvp_analysis = analyze_features_with_ai(prd, priorities)
+
+          {
+            mvp_features: mvp_analysis[:must_have],
+            deferred_features: mvp_analysis[:nice_to_have],
+            out_of_scope: mvp_analysis[:out_of_scope],
+            success_criteria: mvp_analysis[:success_criteria],
+            assumptions: mvp_analysis[:assumptions],
+            risks: mvp_analysis[:risks],
+            metadata: {
+              generated_at: Time.now.iso8601,
+              mvp_feature_count: mvp_analysis[:must_have].size,
+              deferred_feature_count: mvp_analysis[:nice_to_have].size,
+              out_of_scope_count: mvp_analysis[:out_of_scope].size,
+              user_priorities: priorities
+            }
+          }
+        end
+
+        # Format MVP scope as markdown
+        # @param mvp_scope [Hash] MVP scope structure
+        # @return [String] Markdown formatted MVP scope
+        def format_as_markdown(mvp_scope)
+          Aidp.log_debug("mvp_scope_generator", "format_as_markdown")
+
+          output = ["# MVP Scope Definition", ""]
+          output << "**Generated:** #{mvp_scope[:metadata][:generated_at]}"
+          output << "**MVP Features:** #{mvp_scope[:metadata][:mvp_feature_count]}"
+          output << "**Deferred Features:** #{mvp_scope[:metadata][:deferred_feature_count]}"
+          output << ""
+
+          output << "## Overview"
+          output << ""
+          output << "This document defines the Minimum Viable Product (MVP) scope, distinguishing between must-have features for initial release and nice-to-have features that can be deferred to later iterations."
+          output << ""
+
+          output << "## User Priorities"
+          output << ""
+          mvp_scope[:metadata][:user_priorities].each_with_index do |priority, idx|
+            output << "#{idx + 1}. #{priority}"
+          end
+          output << ""
+
+          output << "## MVP Features (Must-Have)"
+          output << ""
+          output << "These features are essential for the MVP and must be included in the first release:"
+          output << ""
+          mvp_scope[:mvp_features].each_with_index do |feature, idx|
+            output << "### #{idx + 1}. #{feature[:name]}"
+            output << ""
+            output << feature[:description] if feature[:description]
+            output << ""
+            output << "**Rationale:** #{feature[:rationale]}" if feature[:rationale]
+            output << ""
+            output << "**Acceptance Criteria:**"
+            (feature[:acceptance_criteria] || []).each do |criterion|
+              output << "- #{criterion}"
+            end
+            output << ""
+          end
+
+          output << "## Deferred Features (Nice-to-Have)"
+          output << ""
+          output << "These features can be implemented in future iterations:"
+          output << ""
+          mvp_scope[:deferred_features].each_with_index do |feature, idx|
+            output << "### #{idx + 1}. #{feature[:name]}"
+            output << ""
+            output << feature[:description] if feature[:description]
+            output << ""
+            output << "**Deferral Reason:** #{feature[:deferral_reason]}" if feature[:deferral_reason]
+            output << ""
+          end
+
+          output << "## Out of Scope"
+          output << ""
+          output << "These items are explicitly out of scope for the MVP:"
+          output << ""
+          mvp_scope[:out_of_scope].each do |item|
+            output << "- #{item}"
+          end
+          output << ""
+
+          output << "## Success Criteria"
+          output << ""
+          output << "The MVP will be considered successful if:"
+          output << ""
+          mvp_scope[:success_criteria].each do |criterion|
+            output << "- #{criterion}"
+          end
+          output << ""
+
+          output << "## Assumptions"
+          output << ""
+          mvp_scope[:assumptions].each do |assumption|
+            output << "- #{assumption}"
+          end
+          output << ""
+
+          output << "## Risks"
+          output << ""
+          mvp_scope[:risks].each_with_index do |risk, idx|
+            output << "#{idx + 1}. **#{risk[:title]}**"
+            output << "   - **Impact:** #{risk[:impact]}"
+            output << "   - **Mitigation:** #{risk[:mitigation]}"
+            output << ""
+          end
+
+          output.join("\n")
+        end
+
+        private
+
+        # Collect user priorities interactively
+        def collect_user_priorities(prd)
+          Aidp.log_debug("mvp_scope_generator", "collect_user_priorities")
+
+          @prompt.say("Let's define your MVP priorities.")
+          @prompt.say("")
+
+          priorities = []
+
+          # Ask about key priorities
+          priorities << @prompt.ask("What is the primary goal of this MVP?", required: true)
+          priorities << @prompt.ask("What is the main problem you're solving?", required: true)
+
+          # Ask about target users
+          target_users = @prompt.ask("Who are your target users?", required: true)
+          priorities << "Target users: #{target_users}"
+
+          # Ask about timeline
+          timeline = @prompt.ask("What is your target timeline for MVP launch? (e.g., 3 months)", required: true)
+          priorities << "Timeline: #{timeline}"
+
+          # Ask about constraints
+          if @prompt.yes?("Do you have any resource or technical constraints?")
+            constraints = @prompt.ask("What constraints should we consider?")
+            priorities << "Constraints: #{constraints}"
+          end
+
+          Aidp.log_debug("mvp_scope_generator", "priorities_collected", count: priorities.size)
+          priorities
+        end
+
+        # Use AI Decision Engine to analyze features and determine MVP scope
+        # This is ZFC - semantic analysis goes to AI, not code
+        def analyze_features_with_ai(prd, priorities)
+          Aidp.log_debug("mvp_scope_generator", "analyze_features_with_ai")
+
+          # Build prompt for AI analysis
+          prompt = build_mvp_analysis_prompt(prd, priorities)
+
+          # Define schema for structured output
+          schema = {
+            type: "object",
+            properties: {
+              must_have: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: {type: "string"},
+                    description: {type: "string"},
+                    rationale: {type: "string"},
+                    acceptance_criteria: {type: "array", items: {type: "string"}}
+                  },
+                  required: ["name", "description", "rationale"]
+                }
+              },
+              nice_to_have: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: {type: "string"},
+                    description: {type: "string"},
+                    deferral_reason: {type: "string"}
+                  },
+                  required: ["name", "description", "deferral_reason"]
+                }
+              },
+              out_of_scope: {
+                type: "array",
+                items: {type: "string"}
+              },
+              success_criteria: {
+                type: "array",
+                items: {type: "string"}
+              },
+              assumptions: {
+                type: "array",
+                items: {type: "string"}
+              },
+              risks: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    title: {type: "string"},
+                    impact: {type: "string"},
+                    mitigation: {type: "string"}
+                  }
+                }
+              }
+            },
+            required: ["must_have", "nice_to_have", "success_criteria"]
+          }
+
+          # Call AI Decision Engine
+          decision = @ai_decision_engine.decide(
+            context: "mvp_scope_analysis",
+            prompt: prompt,
+            data: {
+              prd: prd,
+              priorities: priorities
+            },
+            schema: schema
+          )
+
+          Aidp.log_debug("mvp_scope_generator", "ai_analysis_complete",
+            must_have: decision[:must_have].size,
+            nice_to_have: decision[:nice_to_have].size)
+
+          decision
+        end
+
+        def build_mvp_analysis_prompt(prd, priorities)
+          <<~PROMPT
+            Analyze the following Product Requirements Document (PRD) and user priorities to determine the Minimum Viable Product (MVP) scope.
+
+            USER PRIORITIES:
+            #{priorities.map.with_index { |p, i| "#{i + 1}. #{p}" }.join("\n")}
+
+            PRD SUMMARY:
+            #{prd[:content] || prd.inspect}
+
+            TASK:
+            1. Identify MUST-HAVE features that are absolutely essential for the MVP
+               - These should address the primary goal and solve the main problem
+               - Consider the target users and timeline
+               - Focus on core functionality that delivers value
+
+            2. Identify NICE-TO-HAVE features that can be deferred to future iterations
+               - These are valuable but not critical for initial release
+               - Explain why each can be deferred
+
+            3. Identify items that are OUT OF SCOPE for the MVP
+               - Features that don't align with MVP goals
+               - Advanced features that can wait
+
+            4. Define SUCCESS CRITERIA for the MVP
+               - Measurable outcomes
+               - User satisfaction metrics
+               - Technical performance targets
+
+            5. List ASSUMPTIONS
+               - What are we assuming about users, technology, or resources?
+
+            6. Identify RISKS
+               - What could prevent MVP success?
+               - What's the impact and mitigation strategy?
+
+            For each must-have feature, provide:
+            - Clear name
+            - Description
+            - Rationale (why it's essential for MVP)
+            - Acceptance criteria (how we know it's done)
+
+            For each nice-to-have feature, provide:
+            - Clear name
+            - Description
+            - Deferral reason (why it can wait)
+
+            Be pragmatic and focus on delivering value quickly while managing scope.
+          PROMPT
+        end
+      end
+    end
+  end
+end