HandShake Acknowledgement Generator
Generates the Somnio HandShake - Step 3 Acknowledgement PDF from raw EM notes. Handles single or batch generation (1 to N devs in one run).
Context
Somnio Software runs a bi-annual performance review program called HandShake (April and October/November). After conducting interviews with the PM, a dev from the team, and the Tech Lead, the EM synthesizes everything into the Acknowledgement document — a formal PDF delivered to the developer.
Input
One or more ficha files (PDF, DOCX, or pasted text) per developer, containing:
- Notes from PM interview
- Notes from dev team member interview
- Notes from Tech Lead review
- EM synthesis / general feedback
- Optionally: previous Acknowledgement PDF (for comparison section)
Input is always free-form — Claude must interpret it intelligently.
Output
One PDF per developer, matching the Somnio Acknowledgement template:
- Somnio logo top-right header, gradient background, transparent footer
- Header table: Somnier, Líder, Fecha, Rol del Somnier
- Puntos abordados (standard agenda — always the same)
- Resumen del encuentro: Seniority · Rendimiento actual · Comparación anterior (if applicable)
- Objetivos acordados: Oportunidad de mejora + Continuar trabajando en
- Aclaración o comentarios generales (optional)
Batch Workflow (ALWAYS follow this order)
Step 1 — Read all attached files
When the EM attaches one or more ficha files, read all of them before asking anything. For each file, extract as much as possible:
- Developer name (Somnier)
- EM / Líder name
- Role
- Current seniority level
- Target level
- All feedback content
Step 2 — Show confirmation table
Present a single summary table with one row per developer. Pre-fill every field Claude could infer. Mark fields Claude could NOT determine with [?].
Example format:
Encontré X fichas. Antes de generar, confirmá o corregí los datos:
| # | Somnier | Líder | Fecha | Rol |
|---|---------|-------|-------|-----|
| 1 | John Doe | Jane Smith | [?] | Sr Flutter Developer |
| 2 | Bob Johnson | [?] | [?] | Sr Backend Engineer |
Completá los [?] y avisame si hay algo para corregir. Una vez confirmado, genero todos los PDFs.Date format rule: Fecha must be Dec 19, 2025 style (abbreviated English month, no leading zero, 4-digit year). Accept any format from the EM and normalise automatically.
Do NOT generate any PDF until the EM explicitly confirms the table.
Step 3 — Generate all PDFs
Once the EM confirms (even partially, e.g. "el resto está bien"), generate all PDFs sequentially. For each dev:
- Build the content JSON from the ficha notes
- Run the generation script
- Report progress: "✅ 1/3 — John Doe.pdf generado"
Deliver all files at the end together.
Step 4 — Deliver
Present all generated PDFs at once using present_files. Name each file: Handshake_Acknowledgement_Firstname_Lastname.pdf
Content Synthesis Guide
From the raw notes, synthesize per developer:
Rendimiento actual
4–7 bullet points highlighting strengths and achievements. Extract from PM/dev/TL feedback. Reformulate cleanly — do not copy raw notes verbatim.
Comparación reunión anterior
Only if a previous Acknowledgement PDF was provided. For each prior objective, assign:
Logrado— clearly achievedLogrado, pero hay que seguir trabajando— partialEn progreso— started but not there yetPendiente— not yet addressed
If no previous eval: omit this section entirely.
Oportunidad de mejora
3–6 specific, actionable improvement areas. Extract from TL/PM criticism. Frame positively and professionally.
Continuar trabajando en
Grouped by category. For Flutter devs, typical categories:
- Conocimientos Técnicos
- Conocimientos Avanzados y Especialización
- Mejora Continua y Arquitectura
- Liderazgo y Comunicación
- Innovación y Uso de Inteligencia Artificial
Adapt categories to the actual role and tech stack.
Running the Generation Script
python3 /path/to/handshake-acknowledgement/scripts/generate_pdf.py \
--somnier "FULL NAME" \
--lider "LEADER NAME" \
--fecha "Dec 19, 2025" \
--rol "Role Title" \
--output /mnt/user-data/outputs/Handshake_Acknowledgement_Firstname_Lastname.pdf \
--content /tmp/handshake_content_firstname.jsonThe script auto-normalises the date format. See scripts/generate_pdf.py for the full content JSON structure.
Important Notes
- Language: Spanish throughout.
- Tone: Professional, constructive, empathetic — the document is read by the developer.
- Seniority levels at Somnio: Junior → Semi-Senior → Senior Medium → Senior Advance → Tech Lead
- Puntos abordados is always the same standard agenda — never change it.
- If a section has no content (no previous eval, no dev comments), omit it entirely.
- Fonts: Nunito 11pt for content, Plus Jakarta Sans 9pt for footer. If TTF files are not present in
assets/fonts/, Liberation Sans is used as fallback. To install proper fonts, place TTF files there (see script docstring).