Weekly Business Report

Weekly Business Report Generator

Pull data from multiple business systems, synthesize it into a coherent narrative, and produce an executive-ready weekly report that turns raw numbers into strategic insight.

Contents

• references/configuration.md — first-run setup questions, directory layout, full config.yaml, and kpi-history.json schema.
• references/data-and-calculations.md — per-source data collection, trend indicators, target comparison, rolling averages, anomaly detection, comparison modes, custom KPI groups, quality rules, and error handling.
• references/output-template.md — the full report markdown template and detail levels.

Workflow

First run (no configuration exists)

1. Run the setup questions and create the directory layout. See references/configuration.md. 2. Generate config.yaml and templates/kpi-definitions.yaml from the schema in references/configuration.md. 3. Initialize history/kpi-history.json using the schema in references/configuration.md.

Each subsequent run

1. Read config.yaml and templates/kpi-definitions.yaml. 2. Determine the reporting period (the previous full business week). 3. Pull data from each enabled source and snapshot it to data/{date}/. See references/data-and-calculations.md. 4. Calculate every KPI: trend indicators, target comparison, rolling averages, and anomalies. See references/data-and-calculations.md. 5. Compare against targets and prior weeks; flag anomalies. 6. Generate the report from the template in references/output-template.md, tailored to each recipient's detail level. 7. Save the report to reports/{date}-weekly-report.md and append this week's values to history/kpi-history.json.

Quick Commands

• "Generate this week's report" — full report for the most recent complete week.
• "Show me revenue trends" — revenue-specific trend analysis with 4-8 week history.
• "What are the concerns this week?" — concerns-only output.
• "Add KPI [name]" — add a new KPI to tracking (see custom KPI groups in references/data-and-calculations.md).
• "Update targets" — modify target values for existing KPIs.
• "Compare last 4 weeks" — side-by-side comparison of the last 4 weekly reports.
• "YTD summary" — year-to-date summary across all tracked KPIs.

Apply the report quality rules and error handling in references/data-and-calculations.md to every run.

Configuration

Directory Structure

Create this layout on first run:

weekly-reports/
  config.yaml                    # Report configuration
  templates/
    report-template.md           # Report template
    kpi-definitions.yaml         # KPI definitions and targets
  data/
    {date}/                      # Raw data snapshots per week
      revenue.json
      pipeline.json
      marketing.json
      product.json
      support.json
  reports/
    {date}-weekly-report.md      # Generated reports
  history/
    kpi-history.json             # Historical KPI data for trends

First-Run Setup Questions

Guide the user through setup when no configuration exists:

1. Company context: company name and what they sell. 2. Reporting period: which day the business week starts (default: Monday). 3. Data sources available:

• Supabase database (analytics, user data, events)
• CRM (HubSpot, Salesforce, or custom)
• Financial data (spreadsheets, accounting software exports)
• Email marketing platform (Mailchimp, SendGrid, etc.)
• Google Analytics or equivalent
• Stripe or payment processor
• Support ticket system
• Custom APIs

4. KPIs that matter most (offer the default set below, let them customize). 5. Distribution: recipient names and roles for tailoring depth. 6. Output directory (default: ./weekly-reports/).

config.yaml

version: "1.0"
company:
  name: ""
  product: ""
  fiscal_year_start: "January"
  week_start: "Monday"

data_sources:
  supabase:
    enabled: false
    project_id: ""
    tables:
      users: "auth.users"
      events: "public.events"
      subscriptions: "public.subscriptions"
  crm:
    enabled: false
    platform: ""           # hubspot, salesforce, custom
    connection: ""
  financial:
    enabled: false
    source: ""             # spreadsheet path, API endpoint
    format: ""             # csv, xlsx, json
  email:
    enabled: false
    platform: ""           # mailchimp, sendgrid, custom
  analytics:
    enabled: false
    platform: ""           # google-analytics, mixpanel, custom
  payments:
    enabled: false
    platform: ""           # stripe, custom
  support:
    enabled: false
    platform: ""           # intercom, zendesk, custom

kpis:
  revenue:
    - name: "Weekly Revenue"
      source: "payments"
      query: ""
      target: null
      format: "currency"
    - name: "MRR"
      source: "payments"
      query: ""
      target: null
      format: "currency"
    - name: "ARR"
      source: "payments"
      query: ""
      target: null
      format: "currency"
    - name: "Revenue Growth Rate"
      source: "calculated"
      formula: "(current_week_revenue - previous_week_revenue) / previous_week_revenue"
      target: null
      format: "percentage"
  pipeline:
    - name: "New Leads"
      source: "crm"
      query: ""
      target: null
      format: "number"
    - name: "Qualified Opportunities"
      source: "crm"
      query: ""
      target: null
      format: "number"
    - name: "Pipeline Value"
      source: "crm"
      query: ""
      target: null
      format: "currency"
    - name: "Deals Closed"
      source: "crm"
      query: ""
      target: null
      format: "number"
    - name: "Win Rate"
      source: "calculated"
      formula: "deals_won / (deals_won + deals_lost)"
      target: null
      format: "percentage"
  product:
    - name: "Active Users"
      source: "supabase"
      query: ""
      target: null
      format: "number"
    - name: "New Signups"
      source: "supabase"
      query: ""
      target: null
      format: "number"
    - name: "Feature Adoption"
      source: "supabase"
      query: ""
      target: null
      format: "percentage"
    - name: "Churn Rate"
      source: "calculated"
      formula: "churned_users / start_of_week_users"
      target: null
      format: "percentage"
  marketing:
    - name: "Website Visitors"
      source: "analytics"
      query: ""
      target: null
      format: "number"
    - name: "Email Open Rate"
      source: "email"
      query: ""
      target: null
      format: "percentage"
    - name: "Email Click Rate"
      source: "email"
      query: ""
      target: null
      format: "percentage"
    - name: "Content Published"
      source: "manual"
      target: null
      format: "number"
  support:
    - name: "Tickets Opened"
      source: "support"
      query: ""
      target: null
      format: "number"
    - name: "Tickets Resolved"
      source: "support"
      query: ""
      target: null
      format: "number"
    - name: "Avg Resolution Time"
      source: "support"
      query: ""
      target: null
      format: "duration"
    - name: "CSAT Score"
      source: "support"
      query: ""
      target: null
      format: "score"

distribution:
  recipients:
    - name: ""
      role: ""
      detail_level: "executive"   # executive, manager, detailed
  format: "markdown"

schedule:
  day: "Monday"
  time: "08:00"
  timezone: "America/New_York"

kpi-history.json

Maintain history/kpi-history.json to enable trend analysis:

{
  "version": "1.0",
  "weeks": [
    {
      "week_start": "2026-04-06",
      "week_end": "2026-04-12",
      "kpis": {
        "weekly_revenue": 0,
        "mrr": 0,
        "arr": 0,
        "new_leads": 0,
        "qualified_opportunities": 0,
        "pipeline_value": 0,
        "deals_closed": 0,
        "win_rate": 0,
        "active_users": 0,
        "new_signups": 0,
        "churn_rate": 0,
        "website_visitors": 0,
        "email_open_rate": 0,
        "tickets_opened": 0,
        "tickets_resolved": 0,
        "avg_resolution_time_hours": 0,
        "csat_score": 0
      },
      "highlights": [],
      "concerns": [],
      "action_items": []
    }
  ]
}

Data Collection and KPI Calculations

Data Collection by Source

Supabase

1. Use the Supabase connection details from config. 2. Query the specified tables for the reporting period. 3. Common queries:

• New user signups: SELECT COUNT(*) FROM auth.users WHERE created_at >= [start] AND created_at < [end]
• Active users: SELECT COUNT(DISTINCT user_id) FROM events WHERE created_at >= [start] AND created_at < [end]
• Subscriptions: SELECT plan, COUNT(*), SUM(amount) FROM subscriptions WHERE status = 'active'

4. Store raw query results in data/{date}/.

Spreadsheets (Financial)

1. Read the spreadsheet file (CSV, XLSX). 2. Parse relevant columns and rows for the reporting period. 3. Extract revenue figures, expense categories, and financial metrics. 4. Store parsed data in data/{date}/financial.json.

CRM

1. Query the CRM for the reporting period. 2. Extract pipeline data: new leads, qualified opportunities, closed deals. 3. Calculate conversion rates between pipeline stages. 4. Store in data/{date}/pipeline.json.

Manual Data Entry

1. Present the user with the list of manual KPIs needing values. 2. Accept input as KPI Name: Value. 3. Store in data/{date}/manual.json. 4. Track which KPIs are manual vs automated for future automation recommendations.

Trend Indicators

For each KPI, compute and display a trend indicator:

• [UP] Value increased week-over-week (include % change)
• [DOWN] Value decreased week-over-week (include % change)
• [FLAT] Value changed less than 2% week-over-week
• [NEW] First week tracking this KPI (no comparison available)

Target Comparison

For KPIs with targets:

• [ON TRACK] Within 10% of target pace
• [AHEAD] More than 10% above target pace
• [BEHIND] More than 10% below target pace
• [AT RISK] More than 25% below target pace

Rolling Averages and Aggregates

Compute and display:

• 4-week rolling average (smooths weekly volatility)
• Week-over-week change (absolute and percentage)
• Month-to-date total (for cumulative metrics like revenue)
• Quarter-to-date total
• Year-to-date total (where applicable)

Anomaly Detection

Flag KPIs showing unusual behavior:

• Value more than 2 standard deviations from the 4-week average
• Sudden reversal of a multi-week trend
• New all-time high or low
• Missing data (source unavailable)

Comparison Modes

• Week-over-Week: default comparison
• Month-over-Month: for monthly metrics
• Year-over-Year: for seasonal businesses
• vs Plan: compare actual to planned/budgeted numbers
• vs Cohort: compare against a reference cohort (e.g., same week last year)

Custom KPI Groups

To define a custom KPI group beyond the defaults, collect:

1. KPI name and description 2. Data source and query/formula 3. Target value and measurement unit 4. Trend direction preference (higher is better vs lower is better) 5. Alert thresholds

Report Quality Rules

1. Numbers are king. Back every claim with specific data. State "revenue increased 12% to $47,500", not "revenue improved". 2. Context over data. Always include comparison (WoW, vs target, vs 4-week average). 3. Lead with insight. The executive summary tells the story, not just the dashboard. State what the data means for the business. 4. Honest assessment. Do not sugarcoat bad numbers. Frame concerns constructively but do not hide them. 5. Actionable recommendations. Every concern gets a suggested action. Every trend gets an implication. 6. Consistent format. Use the same structure every week. 7. Brevity for executives. Executive summary and dashboard read in under 2 minutes. Details go below. 8. Source transparency. Note where data came from and flag any gaps.

Error Handling

• Data source unavailable: note it in the report, use most recent available data with a staleness warning.
• Missing KPIs: generate the report with available data, list missing KPIs in the appendix.
• Calculation errors: flag the affected KPI, show raw data, note the error.
• No historical data: generate the report without trend analysis, note it is the first report in the series.
• Partial data: generate the report with what is available, clearly mark sections based on partial data.

Report Output Template

Generate the weekly report following this structure.

# Weekly Business Report
**Company**: [Company Name]
**Week**: [Start Date] - [End Date]
**Generated**: [Generation Date and Time]

---

## Executive Summary

[3-5 sentences capturing the most important takeaways from the week.
Lead with the biggest win or concern. Include one forward-looking statement.]

---

## KPI Dashboard

### Revenue & Financial
| Metric | This Week | Last Week | Change | 4-Wk Avg | Target | Status |
|--------|-----------|-----------|--------|----------|--------|--------|
| Weekly Revenue | $X | $X | [UP] X% | $X | $X | [ON TRACK] |
| MRR | $X | $X | [UP] X% | $X | $X | [AHEAD] |
| ARR | $X | $X | [UP] X% | $X | $X | [ON TRACK] |
| Revenue Growth | X% | X% | -- | X% | X% | [ON TRACK] |

### Sales Pipeline
| Metric | This Week | Last Week | Change | 4-Wk Avg | Target | Status |
|--------|-----------|-----------|--------|----------|--------|--------|
| New Leads | X | X | [UP] X% | X | X | [ON TRACK] |
| Qualified Opps | X | X | [DOWN] X% | X | X | [BEHIND] |
| Pipeline Value | $X | $X | [UP] X% | $X | $X | [AHEAD] |
| Deals Closed | X | X | [FLAT] | X | X | [ON TRACK] |
| Win Rate | X% | X% | [UP] | X% | X% | [ON TRACK] |

### Product & Usage
| Metric | This Week | Last Week | Change | 4-Wk Avg | Target | Status |
|--------|-----------|-----------|--------|----------|--------|--------|
| Active Users | X | X | [UP] X% | X | X | [ON TRACK] |
| New Signups | X | X | [UP] X% | X | X | [AHEAD] |
| Feature Adoption | X% | X% | [UP] | X% | X% | [ON TRACK] |
| Churn Rate | X% | X% | [DOWN] | X% | X% | [ON TRACK] |

### Marketing
| Metric | This Week | Last Week | Change | 4-Wk Avg | Target | Status |
|--------|-----------|-----------|--------|----------|--------|--------|
| Website Visitors | X | X | [UP] X% | X | X | [ON TRACK] |
| Email Open Rate | X% | X% | [UP] | X% | X% | [ON TRACK] |
| Email Click Rate | X% | X% | [FLAT] | X% | X% | [ON TRACK] |
| Content Published | X | X | -- | X | X | [ON TRACK] |

### Customer Support
| Metric | This Week | Last Week | Change | 4-Wk Avg | Target | Status |
|--------|-----------|-----------|--------|----------|--------|--------|
| Tickets Opened | X | X | [DOWN] X% | X | -- | -- |
| Tickets Resolved | X | X | [UP] X% | X | -- | -- |
| Avg Resolution Time | Xh | Xh | [DOWN] | Xh | Xh | [ON TRACK] |
| CSAT Score | X/5 | X/5 | [UP] | X/5 | X/5 | [ON TRACK] |

---

## Highlights

[3-5 positive developments from the week. Be specific with numbers.]

1. **[Category]**: [Specific achievement with data]
2. **[Category]**: [Specific achievement with data]
3. **[Category]**: [Specific achievement with data]

---

## Concerns

[2-4 areas of concern that need attention. Be specific and solution-oriented.]

1. **[Category]**: [Specific concern with data]
   - **Impact**: [What happens if unaddressed]
   - **Suggested Action**: [Concrete next step]

2. **[Category]**: [Specific concern with data]
   - **Impact**: [What happens if unaddressed]
   - **Suggested Action**: [Concrete next step]

---

## Trend Analysis

### Revenue Trajectory
[Analysis of revenue trend over the past 4-8 weeks. Are we accelerating,
decelerating, or steady? What is driving the trend?]

### Pipeline Health
[Analysis of pipeline health. Is the pipeline growing? Are conversion rates
improving? Where are deals getting stuck?]

### Product Engagement
[Analysis of user engagement trends. Are users becoming more or less active?
Which features are gaining traction?]

### Market Signals
[Any relevant market, competitor, or industry signals observed this week]

---

## Action Items

[Specific, actionable items derived from this week's data]

| Priority | Action | Owner | Due Date | Context |
|----------|--------|-------|----------|---------|
| HIGH | [Action] | [Suggested owner] | [Date] | [Why this matters] |
| MEDIUM | [Action] | [Suggested owner] | [Date] | [Why this matters] |
| LOW | [Action] | [Suggested owner] | [Date] | [Why this matters] |

---

## Looking Ahead

### Next Week Focus Areas
- [Focus area 1 based on data]
- [Focus area 2 based on data]
- [Focus area 3 based on data]

### Key Dates and Milestones
- [Upcoming milestone or event relevant to the business]

### Risks to Watch
- [Risk identified from current trends that could materialize next week]

---

## Appendix: Data Sources and Notes

- **Data freshness**: [When each data source was last pulled]
- **Manual entries**: [Which KPIs were manually entered vs automated]
- **Known gaps**: [Any data that could not be collected and why]
- **Methodology changes**: [Any changes to how KPIs are calculated this week]

Detail Levels

• Executive: Dashboard + Executive Summary + Highlights + Concerns + Action Items (1 page)
• Manager: Full report as templated above (2-3 pages)
• Detailed: Full report + appendix with raw data tables, additional breakdowns, and methodology notes (4-5 pages)