summarize-feedback

name	summarize-feedback
description	Synthesize employee feedback from Notion Voice Captures into a professional .docx assessment document. Suggest when — user mentions feedback analysis, performance review, assessment generation, Notion captures, or review preparation.
effort	high
allowed-tools	Read, Glob, Grep, Write, Bash(python:*), Bash(pip:*), AskUserQuestion

You are generating a professional employee feedback assessment document. You will query Notion for feedback entries, synthesize them with Claude, and produce a formatted .docx file. The user may provide arguments: $ARGUMENTS

Input Validation

Required Arguments:

• employee_name="..." - Employee name to match against the "Related To" property in Notion (partial matches supported)

Optional Arguments:

• days=N - Lookback period in days (default: 365, max: 1095)
• start_date=YYYY-MM-DD - Override start date (ISO 8601)
• end_date=YYYY-MM-DD - Override end date (ISO 8601)
• output_path="..." - Custom output file path (default: ./output/Feedback_Summary_{Name}_{datetime}.docx)

If no employee_name is provided, ask the user for it before proceeding.

Prerequisites Check

Before starting, verify all prerequisites:

1. Notion MCP Server

Verify the Notion MCP tools are available (mcp__plugin_Notion_notion__notion-search, mcp__plugin_Notion_notion__notion-fetch). If not connected:

Notion MCP is not connected. Please verify:
1. Notion MCP is configured in your Claude settings
2. The MCP server is running and connected
3. Your Notion API key has access to the Voice Captures database

2. python-docx Package

python -c "import docx; print('python-docx: OK')" 2>/dev/null || echo "python-docx: MISSING"

If missing, ask the user to install: pip install python-docx>=1.0

Step 1: Compute Date Range

Calculate the assessment period:

• If start_date and end_date are provided, use those
• Otherwise: end_date = today, start_date = today minus days parameter (default 365)

Display: Assessment period: {start_date} to {end_date}

Step 2: Query Notion for Feedback Entries

Use the Notion MCP tools to search for feedback entries:

1. Use mcp__plugin_Notion_notion__notion-search to find pages in the Voice Captures database
2. Filter results where:
   • Type property equals "Feedback"
   • Related To property contains the employee_name (case-insensitive partial match)
   • Date property falls within the computed date range

If no entries are found:

No Feedback entries found for "{employee_name}" in the period {start_date} to {end_date}.

Possible causes:
1. No feedback has been captured for this employee
2. The employee name doesn't match the "Related To" property in Notion
   (check for exact spelling, try first name only)
3. The date range is too narrow - try increasing the days parameter

Would you like to:
1. Try a different name or spelling?
2. Expand the date range?
3. List all employees with Feedback entries?

Step 3: Fetch Full Page Content

For each matching entry, use mcp__plugin_Notion_notion__notion-fetch to retrieve the full page content.

Parse the Markdown body to extract:

• Summary (from ## Summary section) - includes Feedback Type (Positive/Constructive/Observation)
• Context (from ## Context section, if present)
• Actionable Items (from ## Actionable Items section, if present)
• Raw Transcript (from ## Raw Transcript section)

Also capture page properties: Title, Date, Tags, Related To.

Display progress: Fetched {N} of {total} entries...

Context Size Guardrail

Before synthesis, evaluate the total volume of feedback entries:

• Entry count exceeds 100: Warn the user before proceeding — the skill makes one Notion API fetch per entry, so 100+ entries means 100+ sequential round-trips and a run that can take 15-30 minutes (see Performance below). This is an operation-cost warning, not a context-size one. Offer to proceed, or narrow the date range to reduce the entry count.
• Total input text exceeds 60% of estimated context window: Warn the user before proceeding. Offer options: (1) reduce the date range, (2) proceed with truncation risk.
• Display warning format:

Context Size Warning
====================
Found {N} feedback entries totaling approximately {word_count} words.
This exceeds the recommended processing threshold.

Then ask with AskUserQuestion:

{
  "questions": [
    {
      "question": "How should the oversized feedback set be processed?",
      "header": "Volume",
      "multiSelect": false,
      "options": [
        {
          "label": "Narrow the date range (Recommended)",
          "description": "Re-run entry collection over a shorter window to reduce entry count and API round-trips"
        },
        {
          "label": "Proceed anyway",
          "description": "Single synthesis pass over everything; risks longer runtime and truncation"
        }
      ]
    }
  ]
}

Step 4: Synthesize Assessment

Feed all structured feedback entries to Claude using the following synthesis prompt. Produce the output as structured JSON.

Synthesis Prompt

You are analyzing employee feedback entries to produce a structured performance assessment.

## Employee
{employee_name}

## Assessment Period
{start_date} to {end_date}

## Feedback Entries
{formatted_entries}

## Instructions

Analyze ALL feedback entries above and produce a structured JSON assessment.
Be specific - cite dates and actual observations from the entries. Do not
fabricate evidence. If there are only a few entries, note the limited sample
size in the executive summary.

The assessment should be balanced and evidence-based. Every strength and area
for development MUST be supported by specific entries with dates.

## Output Format

Return ONLY valid JSON matching this structure:

{
  "executive_summary": "3-5 sentence overall assessment. Note total feedback entries and trajectory (improving, consistent, declining, mixed).",
  "strengths": [
    {
      "name": "Short strength name (2-4 words)",
      "description": "1-2 sentence description of the strength and its impact.",
      "evidence": [
        {
          "date": "YYYY-MM-DD",
          "summary": "Brief reference to the specific feedback entry supporting this strength."
        }
      ],
      "frequency": "Consistent|Frequent|Occasional|Emerging"
    }
  ],
  "areas_for_development": [
    {
      "name": "Short area name (2-4 words)",
      "description": "1-2 sentence description of the development area and why it matters.",
      "evidence": [
        {
          "date": "YYYY-MM-DD",
          "summary": "Brief reference to the specific feedback entry supporting this area."
        }
      ],
      "pattern": "Recurring|Occasional|Situational|Improving"
    }
  ],
  "patterns_and_themes": {
    "trends": "Description of how performance has trended over the assessment period.",
    "relationships": "Connections between different feedback observations.",
    "situational": "Contexts or situations where performance notably varies."
  },
  "recommendations": [
    {
      "type": "Continue|Develop|Stretch",
      "recommendation": "Specific, actionable recommendation.",
      "rationale": "Why this recommendation is important based on the evidence."
    }
  ]
}

## Recommendation Types
- **Continue**: Behaviors and skills to maintain and reinforce
- **Develop**: Areas needing improvement with specific development actions
- **Stretch**: Growth opportunities that build on existing strengths

Format each entry for the prompt as:

### Entry: {title}
- Date: {date}
- Feedback Type: {type}
- Summary: {summary}
- Context: {context}
- Actionable Items: {actionable_items}
- Transcript: {raw_transcript}

Step 5: Generate .docx Document

Build a combined JSON payload with this structure:

{
  "employee_name": "...",
  "assessment_period": { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" },
  "generation_date": "YYYY-MM-DD",
  "total_entries": N,
  "synthesis": { ... },
  "entries": [ ... ]
}

Write the JSON to a temp file in the scratchpad directory.

Determine the output path:

• Use output_path parameter if provided
• Otherwise: ./output/Feedback_Summary_{Employee_Name}_{YYYY-MM-DD_HHMMSS}.docx
  • Replace spaces in employee name with underscores

Run the document generator:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(find ~ -path '*/plugins/personal-plugin' -type d 2>/dev/null | head -1)}"
TOOL_SRC="$PLUGIN_DIR/tools/feedback-docx-generator/src"
PYTHONPATH="$TOOL_SRC" python -m feedback_docx_generator --input {temp_json_path} --output {output_path}

If the script fails, show the error and suggest running it directly for debugging.

Step 6: Report Results

Display a summary:

Feedback Assessment Generated
==============================
Employee:    {employee_name}
Period:      {start_date} to {end_date}
Entries:     {total_entries} feedback entries analyzed
Output:      {output_path}

Document sections:
  1. Executive Summary
  2. Strengths ({N} identified)
  3. Areas for Development ({N} identified)
  4. Patterns and Themes
  5. Recommendations ({N} total)
  6. Appendix: Individual Entries

Performance

Scenario	Expected Duration	Notes
1-10 feedback entries	1-3 minutes	Single-pass synthesis, fast .docx generation
10-50 feedback entries	3-8 minutes	Dominated by Notion fetch and LLM synthesis
50-100 feedback entries	8-15 minutes	Approaching the entry-count warning threshold
100+ feedback entries	15-30 minutes	Triggers the operation-cost warning: 100+ sequential Notion fetches

Duration is dominated by Notion API fetches (Step 3) and LLM synthesis (Step 4). The .docx generation via the Python tool adds under 5 seconds regardless of entry count. The warning at 100+ entries reflects the added wall-clock cost of the additional sequential API fetches, not a context-window concern — synthesis itself remains a single pass regardless of entry count.

Examples

Basic feedback assessment for an employee:

/summarize-feedback employee_name="Jane Smith"

Output: Queries Notion Voice Captures for the last 365 days, synthesizes all feedback entries, and generates ./output/Feedback_Summary_Jane_Smith_20260304_143000.docx.

Assessment with custom date range:

/summarize-feedback employee_name="John Doe" start_date=2025-07-01 end_date=2025-12-31

Output: Scopes feedback to H2 2025 only. Useful for mid-year or quarterly reviews.

Short lookback with custom output path:

/summarize-feedback employee_name="Maria Garcia" days=90 output_path="./reviews/Q1_Maria.docx"

Output: Last 90 days of feedback, written to a custom path.

Typical completion summary:

Feedback Assessment Generated
==============================
Employee:    Jane Smith
Period:      2025-03-04 to 2026-03-04
Entries:     14 feedback entries analyzed
Output:      ./output/Feedback_Summary_Jane_Smith_20260304_143000.docx

Document sections:
  1. Executive Summary
  2. Strengths (4 identified)
  3. Areas for Development (2 identified)
  4. Patterns and Themes
  5. Recommendations (5 total)
  6. Appendix: Individual Entries

Error Handling

Error	Action
No employee_name provided	Ask user for the name
Notion MCP not connected	Abort with configuration instructions
No entries found	Offer to retry with different name/date range
python-docx missing	Abort with install instruction
Synthesis fails	Show error, offer to retry
.docx generation fails	Show error, suggest running script directly