---
name: invoice-prep
description: >
  Show what to put on an invoice for a selected month by checking the user's
  own Tempo timesheets. Lists every Jira project code and the total hours logged
  against it. Warns if there are missing hours or days with no logged time.
  TRIGGER when user asks what to put on an invoice, what to invoice, invoice
  preparation, timesheet summary for invoicing, or similar phrases.
  Trigger phrases: "what should I put on an invoice", "prepare my invoice",
  "invoice for [month]", "what to invoice for", "check my TS for invoice".
---

# Invoice Preparation

Use this skill when someone wants to know what project codes and hours to put on their invoice for a given month. It reads their own Tempo worklogs, groups hours by Jira project, and warns about any missing time.

**In Claude Code, you run the pipeline automatically.** The user provides a month — you handle everything else.

## Prerequisites

Uses the same credentials as the timesheet-checker — no extra setup needed:

| Variable | Purpose |
|---|---|
| `TEMPO_API_TOKEN` | Fetch worklogs from Tempo |
| `JIRA_BASE_URL` | Resolve the user's account ID |
| `JIRA_EMAIL` | Identifies whose timesheets to read |
| `JIRA_API_TOKEN` | Authenticate with Jira |

All four must be present in the `.env` file in the project root.

## Extracting the month

Convert natural language to `YYYY-MM` before running:

| User says | CLI value |
|---|---|
| "last month" | Previous calendar month |
| "this month" | Current calendar month |
| "June", "June 2026" | `2026-06` |
| "May" | `2026-05` (current year) |

If no month is specified, ask: "Which month should I check? (e.g. last month, June 2026)"

## Workflow

**Step 1 — Run the script:**

```bash
python3 {SKILL_DIR}/scripts/run.py \
  --month {YYYY-MM} \
  --output-dir ./timesheet-output
```

This resolves the user's Jira account, fetches their Tempo worklogs for the full calendar month, groups hours by Jira project code, checks completeness against the Polish working calendar, and writes `invoice_prep_{YYYY-MM}.json` to `./timesheet-output/`.

**Step 2 — Present results.** Read the output JSON and show the user:

1. A table of project codes and hours — formatted ready to copy onto an invoice.
   Include **every project in the `projects` array**. Do NOT label any project as "non-billable" or omit it from the table — the script already excludes ignored issues; everything remaining is billable:

   ```
   | Project | Hours |
   | IAA     | 45.5  |
   | PROJ    | 22.0  |
   ```

   Below the table, note ignored issues and their hours as a parenthetical: `(INTERNAL-1: 40h ignored per config.)` — do not mix them into the billable table.

2. The **total billable hours** from `total_billable_hours` (not `total_logged_hours`).

3. If `missing_hours > 0`: a clear warning showing:
   - How many hours are missing vs the expected total for the month
   - Which specific dates have no logged time (up to 10; if more, show count)
   - Reminder to complete the timesheet before issuing the invoice

4. If `total_logged_hours == 0`: warn that no hours were found at all for the month.

## Guardrails

- Never fabricate or estimate hours. All data comes from Tempo.
- If `JIRA_EMAIL` is not set, stop and tell the user.
- If any script step fails, show the error and stop.
- Always remind the user that incomplete timesheets will cause Jira compliance failures when the invoice is checked.