---
name: check-my-timesheet
description: >
  Two behaviours in one skill:
  (1) CHECK — show the current user's timesheet gaps for a given period. Compares
  Tempo worklogs against the working calendar and flags missing or partial days.
  (2) LOG — help the user log time to Tempo. User provides a description or issue key;
  Claude searches Jira if needed, confirms the entry, then posts it.
  TRIGGER check when user says: "check my timesheet", "timesheet gaps", "where am I missing
  hours", "did I log all hours", "show my missing time".
  TRIGGER log when user says: "log time", "add time entry", "log hours", "report hours",
  "book time on", "add worklog".
---

# Check My Timesheet

Personal timesheet checker and time logger for the user identified by `JIRA_EMAIL`.

## Prerequisites

All configuration lives in the `.env` file in the project root:

| Variable | Purpose | Default |
|---|---|---|
| `TEMPO_API_TOKEN` | Read and write Tempo worklogs | — |
| `JIRA_BASE_URL` | Resolve account ID and search issues | — |
| `JIRA_EMAIL` | Identifies whose timesheet to read / who is logging | — |
| `JIRA_API_TOKEN` | Authenticate with Jira | — |
| `MY_TIMESHEET_COUNTRY` | Country code for public holiday calendar (`PL`, `GB`, `DE`…) | `PL` |
| `MY_TIMESHEET_HOURS_PER_DAY` | Expected working hours per day | `8` |

## Setup

Determine `SKILL_DIR` from the location of this file.

---

## Behaviour 1 — Check timesheet gaps

### Trigger phrases
"check my timesheet", "timesheet gaps", "where am I missing hours", "did I log all hours",
"show my time", "show my missing time"

### Workflow

**Step 1 — Ask for period.** Always ask — never assume a default:
> "Which period should I check? (e.g. this week, last week, June 2026, or a date range)"

Convert natural language to `YYYY-MM-DD:YYYY-MM-DD`:
- "this week" → Monday of current week to yesterday
- "last week" → previous Monday–Friday
- "June 2026" → `2026-06-01:2026-06-30`
- "today" → today:today

**Step 2 — Run check:**

```bash
python3 {SKILL_DIR}/scripts/check.py \
  --period {YYYY-MM-DD:YYYY-MM-DD} \
  --output-dir ./timesheet-output
```

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

1. Summary: `Logged X h / Y h expected (Z working days)`
2. If `missing_hours == 0`: "✓ Timesheet complete for this period."
3. Otherwise, a table of all working days — highlight missing and partial:

   ```
   | Date       | Logged | Status   |
   | 2026-06-23 | 8.0 h  | ✓ OK     |
   | 2026-06-24 | 4.0 h  | ⚠ Partial (4h missing) |
   | 2026-06-25 | 0.0 h  | ✗ Missing |
   ```

4. List only the problem days prominently if there are many OK days.

---

## Behaviour 2 — Log time

### Trigger phrases
"log time", "add time entry", "log hours", "report hours", "book time on", "add worklog",
"log X hours on", "log X hours for"

### Workflow

**Step 1 — Collect what is needed:**

From the user's message extract or ask for:
- **Issue** — Jira issue key (e.g. `IAA-42`) or a description to search by
- **Hours** — number of hours (decimals OK: 1.5 = 1h30m)
- **Date** — which day to log on (default: today if not mentioned)
- **Description** — optional note for the worklog

If issue key is not provided but a description is, run a search:

```bash
python3 {SKILL_DIR}/scripts/log.py \
  --mode search \
  --query "{description}"
```

Present the results (up to 5 issues) and ask the user to pick one or confirm.
If no results found, ask the user to provide the issue key directly.

**Step 2 — Preview (run without --confirmed).** Always run the preview step first:

```bash
python3 {SKILL_DIR}/scripts/log.py \
  --mode log \
  --issue {KEY} \
  --hours {N} \
  --date {YYYY-MM-DD} \
  --description "{description}"
```

The script prints the pending worklog and exits without writing anything.
If hours exceed `MY_TIMESHEET_HOURS_PER_DAY` it also prints a `⚠ WARNING` line.

**Step 3 — Show preview to user and ask for confirmation.** Present the full script output
including any warnings. Wait for explicit yes/no. Do NOT proceed without explicit confirmation.

**Step 4 — Log (only after yes, with --confirmed):**

```bash
python3 {SKILL_DIR}/scripts/log.py \
  --mode log \
  --issue {KEY} \
  --hours {N} \
  --date {YYYY-MM-DD} \
  --description "{description}" \
  --confirmed
```

**Step 5 — Report result.** Show the worklog ID and a confirmation message.
Offer to check the timesheet again to verify the entry is reflected.

---

## Guardrails

- Never log time without explicit user confirmation.
- Always run the preview step first — the `--confirmed` flag must only be added after the user says yes.
- If the preview shows a `⚠ WARNING` (hours exceed daily limit), make sure the user acknowledges it before confirming.
- If `my_timesheet.md` is missing, stop and show the user the template.
- If `JIRA_EMAIL` is not set, stop and ask the user to set it in `.env`.
- If any script step fails, show the error and stop.
- Do not guess the issue key — always search or ask if unsure.