c9336941ac
Add four skills for Tempo/KSeF timesheet and invoice workflows: - check-my-timesheet: show/log the current user's Tempo time entries - timesheet-checker: audit timesheet completion across all reporters - invoice-checker: pull KSeF invoices, check contractors + MF white list - invoice-prep: summarize Tempo hours per Jira project for invoicing Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
149 lines
4.9 KiB
Markdown
149 lines
4.9 KiB
Markdown
---
|
||
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.
|