Work report generator

Work Report Generator

Turn unstructured daily notes and commit messages into a formal reports/YYYY-MM-DD/report.md. Strict no-inference: every task, project assignment, and per-project hour count comes from the user, asked explicitly. Report template, anti-patterns, and closing checklist in RECIPES.md.

1. When to use

Daily or backfilled work reports written in a formal tone, in any language. Triggered by phrases like "generar reporte", "reporte de trabajo", "work report", "daily report", "reporte del día", or the /work-report slash command.

Skip this skill for: changelogs, release notes, retrospectives, CV/resume writing, stand-up summaries — those have different structures and audiences.

2. File layout

All artifacts live under reports/ at the repository root. Each day gets its own folder.

reports/
├── projects.md            persistent catalog of general projects (one bullet per project, with short description)
└── YYYY-MM-DD/
    ├── raw.md              per-day scratchpad: manual raw input, tasks grouped by project, hours per project
    ├── commit.md           commit dump for the day, generated by a commit-fetching tool (e.g. this repo's own worklog CLI, if one exists) — never hand-edited
    └── report.md           formal report, generated/regenerated from raw.md + commit.md

• projects.md is the single source of truth for project names across all reports. Reuse names verbatim so reports stay linkable.
• raw.md is the working scratchpad — append-only during a session. Paste manual raw input (comments, clarifications, tasks not tied to any repo or not covered by a commit), record clarification answers, log per-project hours. It is input to the formal report, alongside commit.md.
• commit.md is the mechanical commit dump for the day — grouped by repo with full commit bodies (subject + blank line + body). It is generated, not authored: never hand-write or hand-edit it mid-session. If the host project has an automated commit-fetch tool, prefer it; otherwise paste commits into commit.md manually using the same grouped-by-repo layout, still full body, never just subjects.
• report.md is the output. Regenerate from raw.md and commit.md at the end of the session. Never edit it by hand mid-session.

Create reports/, projects.md, and the per-day folder lazily on first invocation. Do not pre-seed projects.md with example data. commit.md may not exist for a given day (no commits, or the day's work wasn't commit-driven) — that's normal, not an error.

Filename casing and legacy names. New report folders use lowercase filenames (raw.md, commit.md, report.md, projects.md) going forward. Older folders in a given project may still use a prior convention — uppercase LOG.md/REPORT.md, or lowercase log.md (before it was renamed to raw.md) — leave those as-is; do not rename historical folders unless the user asks.

3. Conversation flow (strict order)

Follow this order every time. Do not skip steps even if inputs are obviously inferable — inference is forbidden (§5).

3.1 Language (once per session)

Ask: "¿En qué idioma quieres el reporte?" (default question in Spanish; switch to English if the user opened the conversation in English).

• Store the answer for the rest of the session. Do not re-ask for subsequent reports in the same session.
• If the user changes language mid-session, honor the new choice for new reports only — do not retroactively rewrite past ones unless asked.
• Scope of the language choice: governs report.md only. raw.md keeps the raw input verbatim in its source language — never translate it, never normalize its formatting. Translation rules (§7) apply only when emitting the report.

3.2 Date

Ask: "¿Para qué fecha es el reporte?" Accept YYYY-MM-DD, "today", "yesterday", or a relative reference. Convert to absolute YYYY-MM-DD and confirm before continuing.

One date per invocation. If the user wants to backfill several days, run the full flow (§3.1 onward) once per date — do not batch multiple days in a single session, do not interleave inputs for different dates. The reason: per-day artifacts (raw.md, report.md) and per-project hours must stay scoped to a single calendar day.

3.3 Project catalog review

1. Read reports/projects.md. If missing or empty, state explicitly: "El catálogo de proyectos está vacío. Vamos a construirlo conforme aparezcan en tus notas."
2. If non-empty, print the current list and ask: "¿Agregar, modificar o eliminar algún proyecto antes de empezar?"
3. Apply changes to projects.md before moving on. Each entry is one line: - <Project Name> — <one-line description>.

3.4 Raw input collection

If reports/<date>/commit.md doesn't exist yet and the host project has an automated commit-fetch tool, offer to run it before asking for manual input — it covers everything commit-derived, so the user doesn't need to re-paste that by hand.

Ask the user to paste:

• Free-form comments about what they did (any order, any granularity).
• Anything not tied to a repo or not covered by any commit — meetings, planning, manual configuration, clarifications, anything a commit dump can't capture.
• Optionally, issue/ticket excerpts — title and body, not titles alone.

Append everything verbatim to raw.md under a ## Raw input section. Preserve the original formatting, language, indentation, and line breaks of what the user pasted. Do not reformat, translate, summarize, or de-duplicate at this stage. Commit dumps do not belong here — they live in commit.md (§2), generated or pasted separately.

3.5 Task extraction and project grouping

This is the preliminary analysis phase. Its only valid output is a list of candidate tasks surfaced as questions for the user. Candidates come from both raw.md's ## Raw input (manual notes) and commit.md (commit bodies), read together — neither is skipped just because the other exists. Specifically:

• Enumerate, don't author. Walk through the raw input and commit bodies, splitting them into discrete candidate tasks. Each candidate is a question to confirm, never a finished bullet.
• Never merge on your own. Merging two raw items into one task requires the user's explicit instruction ("junta esos dos"). Don't merge because items look related, share a verb, or touch the same file.
• Never split on your own. Splitting one raw item into multiple tasks also requires explicit instruction. When ambiguous (one task or two?), ask.
• Never invent. If raw input doesn't describe a task, do not add one to "round things out".

For each candidate task, ask one question:

• Project assignment: "¿A qué proyecto pertenece esta tarea?" Show the current catalog. If the user names a new project, add it to projects.md and confirm the short description.

Do not ask hours per task. Hours are tracked at the project level (§3.6).

Record confirmed tasks under a ## Tasks by project section in raw.md, grouped by project, one bullet per task. Use the user's wording from the clarification, not your paraphrase.

3.6 Per-project hours

Once every task is grouped, walk through the projects with at least one task today. For each, ask:

• "¿Cuánto tiempo total le dedicaste a <Project Name> hoy? (formato: 2h 30min)"

Record under a ## Hours section in raw.md.

Never estimate, round, or derive hours from the number/size of tasks. Ask.

3.7 Confirmation before close

Before generating report.md, ask explicitly: "¿Algo más que agregar antes de cerrar el día?" Wait for an affirmative close — "listo", "ciérralo", "no, genera", "all done", or equivalent — before proceeding to §3.8.

• If the user adds more raw input, return to §3.4 and re-run §3.5–§3.6 on the new input only. Re-ask hours only for projects whose task list changed.
• Pause-and-resume is allowed. The flow does not need to finish in a single uninterrupted exchange. If the user steps away and returns later in the same session (or a future session for the same date), re-read raw.md for that date and resume from the last completed step. Never skip the §3.7 confirmation just because earlier steps already ran.

3.8 Report generation

Only after the explicit close confirmation from §3.7 and after every project with tasks today has a recorded hours figure, generate report.md (§4).

Bullet-count check. Before generating, scan each project section's draft bullet count. If any section would end up with a large number of bullets (roughly 6+), ask the user whether to consolidate related ones into denser, theme-grouped bullets before finalizing — many fragmented bullets describing the same underlying effort make the report harder to follow. Only consolidate after the user agrees; apply the same fact-preservation rule as post-hoc consolidation (§8).

Section-count check. Also scan the number of distinct project sections the day would end up with. If there are many (roughly 6+) and some look like they could plausibly be the same underlying effort — or like one section's work is purely a side-effect of another's — flag which ones look mergeable and ask the user whether to combine them (§8's cross-project consolidation / full section merge), rather than silently generating a long flat list of sections. Don't merge on your own judgment; surfacing the candidates is enough, the user decides.

3.9 Final review

Print the report path and a one-line summary of project totals + day total. Ask if the user wants edits before closing.

4. Report format

The report must be readable as raw text. No tables, no HTML, no emojis, no bold/italic decorators, no code fences, no horizontal rules, no nested bullets, no sub-headings. Only:

• Plain paragraphs.
• Numbered top-level sections: 1. Título, 2. Título, etc.
• Single-level bullets under each section with a - prefix.
• One Tiempo del proyecto line per section; one Tiempo total del día line at the very end.

Section header content. The header after each N. is the project name verbatim from projects.md. Nothing else on that line — no parenthetical decoration ((5h), (crítico), (Q2)), no trailing summary, no duplicated descriptor. Example: 1. Detector de Anomalías Online — not 1. Detector de Anomalías Online (4h 30min).

Task bullets describe the result, not the source artifact. Each bullet says what the work accomplished, in formal prose. Never reference commits, tickets, issues, PRs, or branches as the subject of the bullet — those are inputs to the report, not its content. The user can request explicit commit references via §6, in which case they land in a dedicated Referencias section at the end of the report, never inline in task bullets.

• ✗ - Cerró el ticket OPS-142.
• ✗ - Mergeó el commit que arregla el bug del worker.
• ✗ - Completó el PR de refactor.
• ✓ - Resolvió el timeout en el worker de despacho de la cola de publicaciones.
• ✓ - Refactorizó el módulo de despacho para separar la capa de transporte.

Full template, tone examples, hours-arithmetic rules in RECIPES § 1–2.

Hours arithmetic

• Tiempo del proyecto is the value the user gave directly for that project today — do not derive from anything else.
• Sum project totals to produce Tiempo total del día.
• Normalize: 90min → 1h 30min; 2h 0min → 2h; 0h 45min → 45min.

5. Inference is forbidden

The user's hard rule: never infer what was done. Concretely:

• If raw input says "fixed OPC UA bug", do not write "fixed a critical OPC UA protocol violation" — ask what specifically was fixed, then use the user's words.
• If a commit subject says feat(api): add /reports endpoint, do not write the report based on the commit — ask the user what they did and how to frame it.
• If per-project hours are missing for any project with tasks today, do not estimate, round, or distribute time from the day total. Ask.
• If a project assignment is unclear for a task, do not pick the most recent project. Ask.
• If translation of a technical term is uncertain, follow §7 — do not invent a translation.
• If raw input contains an ambiguous abbreviation, shorthand, or apparent typo (e.g. "la Pi" — could be Raspberry Pi, a mistyped "la API", a project codename, or something else entirely), do not silently expand it to the most plausible reading. Ask what it means. The right expansion can genuinely be "Raspberry Pi" some days and something else entirely on others — the point isn't to avoid one specific answer, it's to never guess when the raw input itself is ambiguous.

When in doubt, ask one specific question. Better to ask twice than to fabricate once.

Boundary with §3.5. The preliminary analysis phase (§3.5) enumerates candidate tasks as questions. That is not inference — surfacing "is this one task or two?" is the legitimate way to extract structure from raw input. Inference is filling in an answer the user never gave: inventing a task, merging two items because they look related, picking a project because it was the most recent one, or paraphrasing a commit subject into a finished bullet.

6. Commits are input-only by default

Commits help the user remember what they did, but they do not appear in the report unless explicitly requested ("incluye los commits", "list the commits", "agrega los SHAs").

• Commits live in reports/<date>/commit.md (§2), grouped by repo, with the full message — subject, blank line, body — not the subject line alone. Same body-not-just-subject rule for issue/ticket dumps pasted into raw.md's raw input.
• Use commit subjects and bodies from commit.md only as memory aids when asking clarification questions in §3.5. Never write a task bullet directly from a commit message.
• If the user asks to include them, append a Referencias section at the very end of report.md, listing <short-sha> <subject> one per line, no decoration. References live only in that section — never inline inside task bullets.

7. Language and technical translation

Scope. These rules govern report.md only. raw.md is verbatim source-language input and is never translated, normalized, or rewritten — translating it would destroy the audit trail.

The report is written in the language chosen in §3.1. Technical English terms follow four rules:

1. Established translation exists → use it, with the English term in parentheses on first use only (throttling → limitación de tasa (throttling)).
2. No clean translation → keep the English term as-is (keep-alive, timeout, endpoint).
3. Acronyms and product names → never translate (OPC UA, SCADA, Raspberry Pi).
4. Function/symbol names from code → preserve verbatim, no translation, no quoting.

Full examples per category in RECIPES § 3. When the output language is English, this section is a no-op.

8. Output deliverables per session

At the end of a session:

• reports/projects.md — updated with any new projects added during the session.
• reports/<date>/raw.md — ## Raw input (manual notes only), ## Tasks by project (grouped), ## Hours (per project).
• reports/<date>/commit.md — commit dump for the day (if any), untouched by hand.
• reports/<date>/report.md — formal report regenerated from raw.md + commit.md, following §4 strictly.

If the user comes back the next day or week to amend a past report, re-read raw.md and commit.md for that date first and re-run the task extraction loop only on new input. Re-ask per-project hours only for projects whose task list changed.

Post-hoc consolidation. The user may separately ask, in a later review pass, to consolidate or reword bullets in an already-generated report.md — e.g. merging bullets that describe the same action twice, grouping fragmented same-theme bullets under one denser bullet, or fixing wording/anglicisms. This is allowed only on explicit request — never do it proactively while generating a report for the first time (though §3.8's bullet-count check does allow asking about it at generation time). Any consolidation must preserve every distinct fact from the bullets being merged; it's about density, not about dropping content. Re-verify Tiempo del proyecto/Tiempo total del día are unchanged after any consolidation pass, and check whether the host project syncs report.md content to any external system (time tracker, invoicing, etc.) that would need re-syncing after the edit — see that project's own CLAUDE.md for specifics.

Cross-project consolidation. When the same underlying action spans multiple repos/projects (e.g. a shared dependency version bump applied across several unrelated services as a side effect of one upgrade effort), prefer consolidating the full narrative under the project section that represents its actual destination or consequence, and leave only a brief cross-reference in the other sections' bullets (e.g. "...(ver <Project>)") instead of repeating the full mechanics in each one. This still requires the same explicit-request gate as other post-hoc consolidation.

Full section merge (hours included). The user may go further and ask to fully merge one project section into another — not just cross-reference it, but remove it as a separate section entirely (e.g. when a day's entries under two small side-project sections turn out to be pure side-effects of that day's work on a third, larger project). This is a bigger step than bullet-level consolidation: it moves a Tiempo del proyecto figure between sections, which changes which project/issue the hours are billed under downstream — always confirm explicitly before doing it, and confirm which sections merge into which survivor. When merging:

• Sum the merged section's hours into the surviving section's Tiempo del proyecto — never drop them, and never split them by guessing which part belongs where.
• Fold the merged section's bullet(s) into the surviving section's task list, keeping every distinct fact.
• Remove the merged section entirely and renumber the remaining sections.
• Re-verify Tiempo total del día is unchanged (it should be — same total time, just regrouped).
• Update the day's raw.md/LOG.md ## Hours section to match the new grouping, so a future amendment doesn't work from a stale record.
• If the host project syncs hours to an external system per project/issue (time tracker, invoicing, etc.), the now-removed section's entry there will be stale, not just outdated — check that project's own CLAUDE.md for how to reconcile it (e.g. explicitly deleting the stale entry, not just re-pushing).

9. Anti-patterns + closing checklist

Full anti-pattern table (12 common mistakes) in RECIPES § 4. Pre-close review checklist in RECIPES § 5.