compare_periods
Analyze productivity trends by comparing statistics between two time periods. Generate HTML and Markdown reports showing changes in metrics like meetings, email, and focus time.
Instructions
Compare productivity statistics between two time periods. Generates comparison reports in HTML and Markdown formats showing trends and changes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period1 | Yes | First period to compare | |
| period2 | Yes | Second period to compare | |
| metrics | No | Metrics to compare (default: all) | |
| output_format | No | Output format(s) to generate (default: both) | both |
| save_to_file | No | Whether to save comparison to summaries directory (default: true) |
Implementation Reference
- src/tools/compare-periods.js:15-102 (handler)The core handler function for the 'compare_periods' tool. It validates input periods, calculates date ranges, generates instructions for data collection, processes comparison data if provided, computes changes between periods, and handles file saving for HTML/Markdown outputs.
export async function comparePeriods(args) { try { if (!args.period1 || !args.period2) { throw { code: 'MISSING_PARAMETER', message: 'Both period1 and period2 must be provided', details: 'Each period should have start_date and end_date', }; } // Calculate date ranges for both periods const period1Range = calculateDateRange({ start_date: args.period1.start_date, end_date: args.period1.end_date, }); const period2Range = calculateDateRange({ start_date: args.period2.start_date, end_date: args.period2.end_date, }); const metrics = args.metrics || ['all']; const outputFormat = args.output_format || config.defaults.outputFormat || 'both'; const saveToFile = args.save_to_file !== false; // Generate comparison instructions const instructions = generateComparisonInstructions(period1Range, period2Range, metrics); const result = { success: true, message: 'Period comparison initiated. Follow instructions to collect data for both periods.', period1: period1Range, period2: period2Range, metrics_to_compare: metrics, output_format: outputFormat, save_to_file: saveToFile, instructions, note: 'This tool helps identify trends by comparing two time periods. Collect the same metrics for both periods, then calculate differences.', }; // If comparison data is provided, process it if (args.comparison_data) { result.comparison = processComparisonData( args.comparison_data, period1Range, period2Range, metrics ); // Save comparison files if requested if (saveToFile && args.comparison_data.html && args.comparison_data.markdown) { const files = []; const filenameBase = `period-comparison-${period1Range.startDate}-vs-${period2Range.startDate}`; if (outputFormat === 'both' || outputFormat === 'html') { const htmlPath = await saveSummary( args.comparison_data.html, `${filenameBase}.html` ); files.push(htmlPath); } if (outputFormat === 'both' || outputFormat === 'markdown') { const mdPath = await saveSummary( args.comparison_data.markdown, `${filenameBase}.md` ); files.push(mdPath); } result.files_saved = files; result.message = `Period comparison completed and saved to ${files.length} file(s).`; } } return result; } catch (error) { if (error.code) { throw error; } throw { code: 'COMPARISON_FAILED', message: 'Failed to compare periods', details: error.message, }; } } - src/tools/index.js:179-237 (schema)JSON Schema defining the input parameters for the compare_periods tool, including required period1 and period2 objects with dates, optional metrics, output_format, and save_to_file.
name: 'compare_periods', description: 'Compare productivity statistics between two time periods. Generates comparison reports in HTML and Markdown formats showing trends and changes.', inputSchema: { type: 'object', properties: { period1: { type: 'object', description: 'First period to compare', properties: { start_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, end_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, }, required: ['start_date', 'end_date'], }, period2: { type: 'object', description: 'Second period to compare', properties: { start_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, end_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, }, required: ['start_date', 'end_date'], }, metrics: { type: 'array', items: { type: 'string', enum: ['meetings', 'slack', 'email', 'focus_time', 'all'], }, description: 'Metrics to compare (default: all)', default: ['all'], }, output_format: { type: 'string', enum: ['both', 'html', 'markdown'], description: 'Output format(s) to generate (default: both)', default: 'both', }, save_to_file: { type: 'boolean', description: 'Whether to save comparison to summaries directory (default: true)', default: true, }, }, required: ['period1', 'period2'], }, }, - src/tools/handler.js:43-45 (registration)Registration of the compare_periods tool in the central handleToolCall switch statement, which dispatches calls to the comparePeriods implementation.
case 'compare_periods': result = await comparePeriods(args); break; - src/tools/compare-periods.js:194-231 (helper)Helper function that calculates absolute and percentage changes between two sets of statistics for various metrics like meeting hours, slack messages, emails, and focus time.
function calculateChanges(stats1, stats2) { const changes = {}; // Helper to calculate change const calcChange = (val1, val2, unit = '') => { const diff = val2 - val1; const percentage = val1 !== 0 ? ((diff / val1) * 100).toFixed(1) : 0; const direction = diff > 0 ? 'increase' : diff < 0 ? 'decrease' : 'no change'; return { value: `${diff > 0 ? '+' : ''}${diff}${unit}`, percentage: `${percentage > 0 ? '+' : ''}${percentage}%`, direction, }; }; // Meeting hours if (stats1.meeting_hours !== undefined && stats2.meeting_hours !== undefined) { changes.meeting_hours = calcChange(stats1.meeting_hours, stats2.meeting_hours, ' hours'); } // Slack messages if (stats1.slack_messages !== undefined && stats2.slack_messages !== undefined) { changes.slack_messages = calcChange(stats1.slack_messages, stats2.slack_messages, ' messages'); } // Emails if (stats1.emails_sent !== undefined && stats2.emails_sent !== undefined) { changes.emails_sent = calcChange(stats1.emails_sent, stats2.emails_sent, ' emails'); } // Focus time if (stats1.focus_time_hours !== undefined && stats2.focus_time_hours !== undefined) { changes.focus_time_hours = calcChange(stats1.focus_time_hours, stats2.focus_time_hours, ' hours'); } return changes; }