knack-goal-tracker

name	Knack Goal Tracker
description	Tracks HTI's performance against both grant and business development goals in real-time. Provides early warning system for goal attainment risks an...
allowed-tools	Edit

Knack Goal Tracker

Purpose

Tracks HTI's performance against both grant and business development goals in real-time. Provides early warning system for goal attainment risks and generates actionable insights.

Grant Goals (2024-2026)

Primary Grant Commitments

const grant_goals = {
  devices: {
    acquire: { target: 3500, unit: "laptops", deadline: "2026-12-31" },
    convert: { target: 2500, unit: "HTI Chromebooks", deadline: "2026-12-31" },
    conversion_rate: { target: 70, unit: "percent", type: "minimum" }
  },

  training: {
    hours: { target: 156, unit: "hours", deadline: "2026-12-31" },
    geographic: { target: 15, unit: "counties", type: "coverage" }
  },

  timeline: {
    start: "2024-01-01",
    end: "2026-12-31",
    duration_months: 24
  }
};

2026 Business Development Goals

const business_goals = {
  donors: {
    unique_orgs: { target: 10, unit: "organizations" },
    recurring: { target: 6, unit: "donors", criteria: "50+ laptops annually" },
    major: { target: 20, unit: "donations", criteria: ">$500 each" }
  },

  financial: {
    grant_match: { target: 65000, unit: "USD" },
    corporate_sponsors: { target: 2, unit: "sponsors" }
  },

  sustainability: {
    recurring_revenue: { target: "sustainable post-grant", type: "qualitative" }
  }
};

Core Functions

check_progress

Purpose: Calculate current progress toward all goals

Parameters:

• goal_targets (object, required): Goal definitions
• live_data (object, optional): Current metrics (default: fetch from Knack)
• as_of_date (date, optional): Point-in-time check (default: now)

Example:

const progress = await check_progress({
  goal_targets: grant_goals,
  live_data: await generate_metrics({ fields: ["acquired", "converted", "train_hours"] })
});

// Output:
// {
//   acquire: {
//     current: 1250,
//     target: 3500,
//     progress_pct: 35.7,
//     status: "behind", // on_track | ahead | behind | at_risk
//     variance: -2250,
//     projected_final: 3125, // Based on current pace
//     will_meet_goal: false
//   },
//   convert: {
//     current: 890,
//     target: 2500,
//     progress_pct: 35.6,
//     status: "behind",
//     variance: -1610,
//     projected_final: 2225,
//     will_meet_goal: false
//   },
//   train_hours: {
//     current: 78,
//     target: 156,
//     progress_pct: 50.0,
//     status: "on_track",
//     variance: -78,
//     projected_final: 156,
//     will_meet_goal: true
//   }
// }

calculate_status

Purpose: Determine if goal is on track based on time elapsed

Logic:

function calculate_status({ current, target, time_elapsed_pct }) {
  const progress_pct = (current / target) * 100;

  // Expected progress = time elapsed
  // e.g., 8 months into 24-month grant = 33.3% expected

  if (progress_pct >= time_elapsed_pct + 10) {
    return "ahead"; // More than 10% ahead of schedule
  } else if (progress_pct >= time_elapsed_pct - 5) {
    return "on_track"; // Within 5% of expected
  } else if (progress_pct >= time_elapsed_pct - 15) {
    return "behind"; // 5-15% behind
  } else {
    return "at_risk"; // More than 15% behind
  }
}

Example:

// 8 months into 24-month grant (33.3% time elapsed)
// Current: 1250 acquired, Target: 3500
// Progress: 35.7% (ahead of timeline!)

const status = calculate_status({
  current: 1250,
  target: 3500,
  time_elapsed_pct: 33.3
});
// Returns: "ahead"

forecast_completion

Purpose: Predict final values and completion dates

Algorithm:

function forecast_completion({ current, target, time_elapsed_months, time_remaining_months }) {
  // Calculate current rate
  const rate_per_month = current / time_elapsed_months;

  // Project forward
  const projected_additional = rate_per_month * time_remaining_months;
  const projected_final = current + projected_additional;

  // Will goal be met?
  const will_meet = projected_final >= target;

  // Estimated completion date (if on current pace)
  const months_to_complete = will_meet
    ? time_elapsed_months + ((target - current) / rate_per_month)
    : null;

  return {
    projected_final: Math.round(projected_final),
    will_meet_goal: will_meet,
    estimated_completion: months_to_complete
      ? addMonths(grant_start_date, months_to_complete)
      : "Will not meet at current pace",
    confidence: calculate_confidence({ current, time_elapsed_months })
  };
}

Example:

const forecast = await forecast_completion({
  current: 1250,
  target: 3500,
  time_elapsed_months: 8,
  time_remaining_months: 16
});

// Output:
// {
//   projected_final: 3750,
//   will_meet_goal: true,
//   estimated_completion: "2025-09-15",
//   confidence: 0.85
// }

generate_dashboard_summary

Purpose: Create visual progress summary for dashboards

Example:

const summary = await generate_dashboard_summary();

// Output:
// {
//   overall_health: "at_risk", // ahead | on_track | behind | at_risk
//   goals: [
//     {
//       name: "Laptops Acquired",
//       current: 1250,
//       target: 3500,
//       progress_pct: 35.7,
//       status: "behind",
//       icon: "⚠️",
//       color: "#FF9800" // HTI warning color
//     },
//     {
//       name: "Training Hours",
//       current: 78,
//       target: 156,
//       progress_pct: 50.0,
//       status: "on_track",
//       icon: "✅",
//       color: "#4CAF50" // HTI success color
//     }
//   ],
//   alerts: [
//     {
//       severity: "high",
//       message: "Acquisition pace 15% below target - increase donor outreach"
//     }
//   ],
//   last_updated: "2025-04-15T14:30:00Z"
// }

identify_risks

Purpose: Flag goals at risk of not being met

Example:

const risks = await identify_risks();

// Output:
// [
//   {
//     goal: "Laptops Acquired",
//     risk_level: "high",
//     current: 1250,
//     target: 3500,
//     gap: -2250,
//     recommendation: "Increase acquisition by 20% per month to meet goal",
//     action_items: [
//       "Contact 5 new potential donor organizations",
//       "Launch Q3 laptop drive campaign",
//       "Engage corporate sponsors for bulk donations"
//     ]
//   },
//   {
//     goal: "Recurring Donors (6 with 50+ laptops)",
//     risk_level: "medium",
//     current: 3,
//     target: 6,
//     gap: -3,
//     recommendation: "Nurture current one-time donors into recurring relationships",
//     action_items: [
//       "Quarterly check-ins with major donors",
//       "Create recurring donation program",
//       "Share impact reports to retain engagement"
//     ]
//   }
// ]

generate_recommendations

Purpose: AI-driven suggestions to get back on track

Example:

const recommendations = await generate_recommendations({
  goal: "acquire",
  current: 1250,
  target: 3500,
  time_remaining_months: 16
});

// Output:
// {
//   required_pace: {
//     per_month: 141,
//     per_week: 33,
//     change_from_current: "+20%"
//   },
//   strategies: [
//     {
//       strategy: "Expand donor outreach",
//       impact: "high",
//       effort: "medium",
//       description: "Target 10 new organizations in underserved counties"
//     },
//     {
//       strategy: "Corporate laptop refresh campaigns",
//       impact: "high",
//       effort: "high",
//       description: "Partner with Triangle-area corporations upgrading devices"
//     },
//     {
//       strategy: "Community laptop drives",
//       impact: "medium",
//       effort: "low",
//       description: "Host collection events in Wake & Durham"
//     }
//   ],
//   confidence: "If implemented, 85% likelihood of meeting goal"
// }

Real-Time Progress Widgets

Progress Bar Component

function render_progress_bar({ current, target, label }) {
  const progress_pct = (current / target) * 100;
  const status_color = get_status_color(progress_pct);

  return {
    label: label,
    current: current,
    target: target,
    progress_pct: progress_pct.toFixed(1),
    bar: {
      width: `${progress_pct}%`,
      color: status_color
    },
    text: `${current.toLocaleString()} / ${target.toLocaleString()}`
  };
}

function get_status_color(progress_pct) {
  if (progress_pct >= 90) return "#4CAF50"; // Green
  if (progress_pct >= 70) return "#6FC3DF"; // HTI Blue
  if (progress_pct >= 50) return "#FF9800"; // Orange
  return "#F44336"; // Red
}

Circular Progress Indicator

function render_circular_progress({ current, target, label }) {
  const progress_pct = (current / target) * 100;

  return {
    type: "circular",
    progress: progress_pct,
    center_text: `${progress_pct.toFixed(0)}%`,
    label: label,
    color: get_status_color(progress_pct),
    stroke_width: 10
  };
}

Countdown to Goal

function render_countdown({ current, target, rate_per_month }) {
  const remaining = target - current;
  const months_left = remaining / rate_per_month;

  return {
    label: "Est. Time to Goal",
    value: months_left > 0 ? `${months_left.toFixed(1)} months` : "Goal Met!",
    icon: months_left < 12 ? "🚀" : "⏳"
  };
}

Alerts & Notifications

Automated Alerts

// Check progress daily, alert if status changes
cron.schedule('0 9 * * *', async () => {
  const progress = await check_progress({ goal_targets: grant_goals });

  // Check each goal
  for (const [goal_name, goal_data] of Object.entries(progress)) {
    const previous_status = await get_previous_status(goal_name);

    if (goal_data.status !== previous_status) {
      await notify_team({
        channel: "#grant-tracking",
        message: `Goal status changed: ${goal_name} is now ${goal_data.status}`,
        data: goal_data
      });
    }

    if (goal_data.status === "at_risk") {
      await notify_admin({
        urgency: "high",
        subject: `ACTION REQUIRED: ${goal_name} at risk`,
        body: `Current: ${goal_data.current}, Target: ${goal_data.target}`,
        recommendations: await generate_recommendations({ goal: goal_name })
      });
    }
  }
});

Quarterly Progress Notifications

// Send stakeholder updates at quarter-end
cron.schedule('0 9 1 1,4,7,10 *', async () => {
  const quarter = getCurrentQuarter();
  const progress = await check_progress({ goal_targets: grant_goals });

  await sendEmail({
    to: "[e-mail]",
    subject: `HTI ${quarter} Goal Progress Update`,
    html: render_progress_email(progress)
  });
});

Integration Points

• knack_reader: Fetch current metrics
• knack_pagination: Retrieve full datasets for accurate counts
• knack_dashboard_ai: Generate forecasts and recommendations
• knack_reporting_sync: Include in quarterly reports
• knack_cache_optimizer: Cache progress calculations (5-min TTL)
• knack_realtime: Live progress updates on dashboard

Dashboard Views

Executive Goal Dashboard

const executive_dashboard = {
  widgets: [
    { type: "kpi_grid", data: await check_progress({ goal_targets: grant_goals }) },
    { type: "progress_bars", data: await generate_dashboard_summary() },
    { type: "forecast_chart", data: await forecast_all_goals() },
    { type: "risk_alerts", data: await identify_risks() }
  ]
};

Operations Goal Dashboard

const ops_dashboard = {
  widgets: [
    { type: "real_time_counter", goal: "acquired", refresh: "live" },
    { type: "pace_indicator", goal: "acquired", unit: "per_month" },
    { type: "action_items", data: await generate_recommendations() },
    { type: "county_coverage_map", data: await county_progress() }
  ]
};

Best Practices

1. Update goals in real-time: Not just quarterly
2. Set intermediate milestones: Monthly or quarterly targets
3. Track leading indicators: Donor pipeline, not just acquisitions
4. Celebrate wins: Alert team when milestones hit
5. Course-correct early: Don't wait until quarter-end to act

Grant Compliance

NCDIT Reporting

• Include goal progress in every quarterly report
• Explain variances >10% from target
• Provide remediation plans for at-risk goals
• Document goal achievement at grant completion