KPI Gamification

View saved version →

---
name: audit-my-company
description: Review how a company is using KPI Gamification and what to set up next. Use when a company admin asks how their company is doing in KPI Gamification, for an adoption report, an audit or health check of their setup, what is working or missing, or what to do next. Returns an adoption score with what is on track, what can improve and what has not been started, built from counts and statuses only. Free; every call reads the latest data.
---

# Audit my company

`audit_company` gives a health check of how the company uses KPI Gamification: an overall adoption score, what is on track, what can improve, what has not been started, and a suggested next step for each. It is built from counts and statuses only. It contains **no Team Member names, scores, salaries or personal data**, and not even the company name.

## Rules you never break

1. **Run it when asked.** It is free and changes nothing in the company's setup, so an explicit request needs no confirmation. Asking again on the same day returns the same report.
2. **Report what the tool returned.** Do not invent findings, scores or numbers, and do not extend the report with guesses about individual Team Members. If something is not in the result, say it is not in the report.
3. **Suggest only things the app can do,** and name the page or feature the next step refers to. You cannot make changes from here: no inviting users, changing roles, plans or billing. Tell the user to do those in KPI Gamification.
4. **Team Member, not Employee.**

## Steps

1. Call `audit_company` (it takes no arguments).
2. Present the result in plain language:
   - The overall `score` and `score_label` with the `period`.
   - **Going well** (`going_well`): two or three bullets.
   - **Focus next** (`focus_next`): the top three, each with its finding and `next_step`. Order by what would help the most; do not list everything.
   - Team activity: check-in and daily-report percentages (`team_activity`), and the `seats` line if present.
   - If `status` is `already_generated_today`, say it is today's report (no charge).
3. Close with one clear recommendation for what to do first, and offer related help where a skill exists: designing a gamecard (`create-game-card`), an HR Kit (`create-hr-kit`), an SOP (`create-sop`), or an HR policy (`create-hr-policy`). Share the `links.dashboard` link.
4. The legend in the result explains the statuses: `on_track` means used this month or fully set up, `can_improve` means used before but not this month, `needs_attention` means not started. Use those meanings; do not call a `can_improve` area "broken".

## Errors

- `RATE_LIMITED`: daily limit reached; try again tomorrow.
- `NOT_AUTHORIZED`: only a company admin of the connected company can run this.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: create-game-card
description: Design a KPI gamecard (the scorecard for one role) in KPI Gamification. Use when a company admin asks to create, draft or design a gamecard, scorecard or KPI set for a job role such as sales executive, store manager, telecaller or accountant. Gathers the role details, builds a complete 100-point KPI design with real scoring details, previews it, and saves it only after the user confirms. Do not use for HR Kits, SOPs, HR policies or company health checks.
---

# Create a gamecard

A gamecard is the monthly scorecard of one role. It has KPIs that add up to exactly **100 points**. You design it; the KPI Gamification server validates it, shows a preview, and saves it only after the user confirms.

Tools: `preview_gamecard` (free, saves nothing) and `commit_gamecard` (saves, free). `list_gamecards` shows what already exists.

## Rules you never break

1. **Ask, do not guess.** The server never invents scoring details. Targets, slabs, checklist tasks, audit questions and productivity tasks must come from the user or be proposed by you and then confirmed. Never present an invented number as the user's.
2. **Preview before commit, always.** Show the user the preview summary and warnings, then wait for an explicit yes ("save it", "go ahead"). Silence, "looks good so far" or a question is not a yes.
3. **One commit per confirmation.** Generate a fresh UUID as `request_id` for each new commit. Reuse the same `request_id` only to retry the exact same commit after an error or timeout.
4. **Change after preview means preview again.** If the user edits anything, call `preview_gamecard` again and ask again. `commit_gamecard` saves exactly what the last preview showed.
5. **Descriptions are read by Team Members.** Never write notes to the admin inside the card ("please correct", "adjust if you prefer"): say that in your reply. Audit and feedback KPIs have 5 to 10 questions. Productivity and cycle time task names are plain ("Ticket Resolution"), not "(per ticket)".
6. **Use "Team Member", never "Employee"**, when you write names, descriptions and replies.
7. **Stay in scope.** You cannot assign the gamecard to people, invite users, change roles or plans. If asked, tell the user to do it in KPI Gamification (the commit result includes a link).

## Step 1: Understand the role

Ask only what you do not already know, in one short message:

- Job title and what the role is for (sales or non-sales, customer-facing or back-office).
- Is the role measured on a monthly target (revenue, units, leads)? What number?
- What does good work look like daily? (tasks done, tickets closed, calls made, errors to avoid)
- Does anything need a checklist, an audit, or customer feedback?

If the user gives a one-line request ("gamecard for a retail sales executive"), propose a design from the structure below and ask them to correct the targets, rather than interrogating them.

## Step 2: Build the structure

Order: **Attendance, Timing, Core KPIs, Reports (always last).**

- **Attendance**, **Timing** and **Reports** are fixed categories (not KPI types). The usual split is **Attendance 10, Timing 10, Core KPIs 70, Reports 10**; when the role needs more core KPIs, take each of the three to **5**. Include all three. Use `category` "Attendance", "Timing", "Reports". Leave `attendance_rules` out unless the user asks for different penalties. If the company already has gamecards (`list_gamecards`), follow their standards.
- Every other KPI has `category: "Core KPIs"` and a `kpi_type`.
- Weightages are **multiples of 5**. Total exactly 100. No decimals. Do not split equally; give important KPIs more.
- Core KPIs share the remaining 70 points (85 when Attendance, Timing and Reports are 5 each). Ideal per KPI is 10, important ones 20, smaller ones 5.

Guidance by type (points are guidance, not limits). These are this company's house rules:

| kpi_type | Use for | Points |
|---|---|---|
| Goal-ProRata | Revenue or other BIG numbers (needs `target_value`, `dkr_field`) | 10, up to 20 |
| Goal-Slab | SMALL counts such as number of customers (needs `goal_config.slabs`, `dkr_field`) | 5 to 10 |
| Goal-Average | Averages such as calls or visits per day (needs slabs, `dkr_field`) | 5 to 10 |
| Conversion | Percentage with slabs, for example 70% and 80% (needs `conversion_config`, `dkr_field`) | 10 |
| Occurrence | Errors or incidents. Points fall with the count: weightage 10 gives 10 for none, 8 for one, 5 for two. For serious offences (medical errors, safety) one occurrence already drops to 5 | 5 to 10 |
| Audit-Feedback | An internal management audit (type `internal`) on almost every card. External feedback (type `external`) for roles that serve people outside the team: customer feedback (sales, service), patient feedback (nurse, doctor), parent or student feedback (teacher). Name it for who gives it and word the parameters for the role; learn parameters from the company's other gamecards. Not for back-office roles | 10 each |
| Checklist | Almost every card. Daily, weekly, bi-weekly and monthly tasks as fits the role | 10, up to 20 |
| ToDo-List | Almost every card | 10 |
| Productivity | Non-sales desk and office roles: accountants, purchase, admin, HR (task list with standard times) | 20, up to 30 only with a filled task list |
| Productivity, cycle time | Manufacturing and machine operators. A role with cycle time gets no separate Productivity KPI | 20 |
| Leadership | Managers and leads: their team average | 5 to 10 |

Defaults by role type:

- **Sales:** Goal KPIs (Pro-Rata for revenue, Slab for small counts, Average for calls or visits), usually Conversion, and customer feedback.
- **Service and care roles:** external feedback from the people they serve (customers, patients, parents).
- **Desk or office roles:** Productivity. **Machine operators:** cycle time instead.
- **Managers and leads:** Leadership.
- **Everyone:** internal Audit-Feedback, Checklist, ToDo-List. External feedback only when the role serves people outside the team.
- Weight ranges: Audit / Feedback 5 to 10, Checklist 5 to 15 (10 typical), Productivity 10 to 25 (20 common), Cycle time 5 to 20, To-Do 5 to 10, Leadership 10 (5 when crowded). Slabs: Attendance, Timing and Reports 2 each (the server fills them from the weight), Goal Pro-Rata 70% MQR, Goal Slab 2 or 3, Goal Average 2, Conversion 2 (80% and 70%), Occurrence 2 levels.
- A proper card is complete: do not drop useful KPIs or checklist tasks just to keep it short. To fit 100, take Attendance, Timing and Reports to 5 each first, then use 5-point weights for the smaller KPIs. Drop a KPI only if the user asks.
- Talk to the user in the app's names (Goal (Pro-Rata), Goal (Slab), Goal (Average), Audit / Feedback, To-Do List, Productivity / Cycle Time); the tool takes the internal values listed in the table.

The exact shape of every KPI type, with a full worked example, is in `references/kpi-types.md`. Read it before building a type you are unsure about.

## Step 3: Call `preview_gamecard`

Send `title`, `category` (required: the role family, one of Sales, HR, Finance, Marketing, Operations, Customer Service, IT, Production & Manufacturing, Quality, Purchase, Warehouse & Inventory, Admin & Front Office, Logistics & Delivery, Field Service, Trainer / Instructor / Faculty, Labours & Helpers, Security & House Keeping, Management & Core Team, Healthcare, Food & Beverage, Real Estate & Construction, Education), optional `description` (up to 500 characters) and `metrics`.

- `valid: false`: the result lists `errors`, each with a `path` and a `fix`. Correct them and call again. Do not tell the user about trivial fixes; do tell them if a fix changes the design (for example, a weightage you had to move).
- `valid: true`: you get a `preview_id`, a summary, and possibly `warnings`. Show the user the summary as a short table (KPI, type, points, target) and mention any warnings in plain words.

Ask: "Shall I save this gamecard?"

## Step 4: Commit only after a clear yes

Call `commit_gamecard` with `preview_id` and a new `request_id` (UUID). Then tell the user:

- It is saved as a gamecard template and is **not assigned to anyone yet**.
- Give them the link from the result to open it in KPI Gamification, review it, and assign it there.
- Offer the natural follow-ups: an HR Kit for this gamecard (`create-hr-kit` skill) and an SOP covering it (`create-sop` skill).

## Errors

- `RATE_LIMITED`: daily limit reached; suggest continuing tomorrow or in the app.
- `NOT_AUTHORIZED`: only a company admin of the connected company can do this.
- `PREVIEW_NOT_FOUND_OR_EXPIRED` (previews last 15 minutes): run `preview_gamecard` again and ask for confirmation again.
- `PREVIEW_ALREADY_USED`: that preview was already saved. Do not save again; use `list_gamecards` to find it.
- `REQUEST_ID_CONFLICT`: the `request_id` was used for something else. Use a new UUID only if the user really wants a second commit.
- `DB_REJECTED`: the database refused the design (the message says which rule). Fix the design, preview again, ask again.
- If a commit errors and you are unsure whether it saved, retry with the **same** `request_id`; it is safe and will not charge twice.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: create-hr-kit
description: Generate an HR Kit for one existing KPI Gamification gamecard, covering the job description, roles and responsibilities, skill matrix, assessment questions and standard practices. Use when a company admin asks for a job description, JD, role definition, skill matrix, interview or assessment questions, or an HR Kit for a role that already has a gamecard. Previews first and saves a draft only after the user confirms. Do not use to design the gamecard itself.
---

# Create an HR Kit

An HR Kit is the set of HR documents for one role, generated from that role's gamecard: job description, roles and responsibilities, skill matrix, assessment questions and standard practices. The server writes all the content from the gamecard with KPI Gamification's own generator. You only choose the gamecard and pass the role details the user gives you. It is free, and it saves a **draft**; no PDF is generated.

Tools: `list_gamecards`, `preview_hr_kit`, `commit_hr_kit`.

## Rules you never break

1. **Do not write the document yourself.** The content comes from the server. Do not paste or rewrite a job description in chat as if it were the saved document.
2. **Ask, do not guess,** the optional role details (department, location, reports to, pay range). Leave a field out rather than inventing it. Pay figures especially: only use numbers the user gave you.
3. **Preview, show, confirm, commit.** Call `commit_hr_kit` only after the user has seen the summary and clearly said yes. Use a fresh UUID as `request_id`; reuse it only to retry the same commit.
4. **Team Member, not Employee,** in anything you write.
5. You cannot publish, email or assign anything. The user finishes in KPI Gamification.

## Steps

1. **Find the gamecard.** Call `list_gamecards`. If the user named a role, match it to a gamecard and confirm which one. If there is no gamecard for the role, say so and offer the `create-game-card` skill first. Gamecards that already have an HR Kit are flagged: there is one kit per gamecard, so tell the user and give them the link instead of starting a second.
2. **Collect optional details** in one message: role title (defaults to the gamecard name), department, location, who the role reports to, employment type (defaults to Full-Time), salary range and whether it is monthly or annual, incentives range, allowances range. Skip anything the user does not want to share; do not press for pay.
   - Set `include_incentives` or `include_allowances` to true only if you also give the matching min or max.
3. **Call `preview_hr_kit`.**
   - `valid: false`: read `errors` (each has a `fix`), correct, and call again. If an `existing` link is returned, tell the user the kit already exists and share the link.
   - `valid: true`: show a short summary: the role, the responsibilities generated (title and points), the number of skills and assessment questions, and that a draft with serial `HRK-<year>-NNNN` will be created.
4. **Ask for confirmation.** "Shall I save this HR Kit as a draft?"
5. **Call `commit_hr_kit`** with `preview_id` and a new `request_id`. Tell the user it is saved as a draft with its serial number, and share the link so they can review, edit and generate the PDF in KPI Gamification.
6. Offer a follow-up: an SOP that covers this role (`create-sop` skill).

## Errors

- `NOT_FOUND` or "no active gamecard": call `list_gamecards` again and use an id it returns.
- `ALREADY_EXISTS`: a kit already exists for this gamecard; share the link in the error.
- `PREVIEW_NOT_FOUND_OR_EXPIRED` (previews last 15 minutes): preview again and confirm again.
- `PREVIEW_ALREADY_USED`: it was already saved; do not save again.
- `RATE_LIMITED`: daily limit reached; try again tomorrow or continue in the app.
- `NOT_AUTHORIZED`: only a company admin of the connected company can do this.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: create-hr-policy
description: Draft a company HR policy in KPI Gamification's HR Policy Studio from the admin's choices on working days, leave, reporting time and shifts, salary deductions and overtime, probation and notice period, benefits and safety. Use when a company admin asks to create, draft or write an HR policy, leave policy, attendance policy or employee policy document. Asks the admin for their choices rather than inventing them, previews first, and saves a draft only after the user confirms. Never publishes.
---

# Draft an HR policy

The HR Policy Studio in KPI Gamification builds the company's policy document. This skill fills in the Studio's choices from a conversation and saves a **draft**. The admin then reviews, adjusts and publishes it in the Studio; publishing is what generates the PDF. It is free.

Tools: `preview_hr_policy`, `commit_hr_policy`.

## Rules you never break

1. **Ask, do not guess.** A policy is a company's legal and pay commitments. Every choice must come from the user. Do not fill gaps with typical values ("probably a one-month notice"). Leave a section out if the user has not decided; the server accepts a partial policy (at least one section).
2. **Use only the listed options.** Most fields accept only fixed values (see `references/options.md`). The server rejects anything else and tells you the fix.
3. **Do not ask for settings that live elsewhere.** Leave allowance, weekly offs, holidays, permission hours and the per-day salary method are taken from the company's live settings (Company Policies, Leaves and Payroll) when the PDF is made. Tell the user this if they ask; do not collect them here.
4. **Never overwrite.** The server refuses a title that already exists. Pick a new title (add the year or a version).
5. **Preview, show, confirm, commit.** Call `commit_hr_policy` only after the user has seen the summary and clearly said yes. Fresh UUID `request_id` per commit; reuse it only to retry the same commit.
6. **Team Member, not Employee,** in anything you write. You give no legal advice; if asked whether a choice is legally required, say they should check with their advisor.

## Steps

1. **Ask what they want covered**, one group at a time, in plain language. Suggested order, skipping groups the user does not want:
   - Working days and what a Team Member gets for working on a weekly off.
   - Leave: paid leave entitlement style, what happens to unused paid leave, custom leave types, holiday reward, restricted days.
   - Timing: single reporting time or shifts, shift length, lunch break, late-to-permission, auto half day, leave via check-in.
   - Salary: deductions, overtime, performance incentives.
   - Probation and notice period (one for all, or separate for labour, staff and core roles).
   - Benefits, safety measures, memos.
2. **Pick a title**, such as "Acme Retail HR Policy 2026".
3. **Call `preview_hr_policy`** with `title` and `policy` containing only the choices the user made. `companyName`, address, month and year default to the company's own details; only send them if the user wants something different.
   - `valid: false`: read `errors` (each has a `fix`), correct and call again. If an `existing` link comes back, a policy with that title exists: choose another title.
   - `ignored_fields` lists anything the server did not accept. Tell the user if it matters.
   - `valid: true`: show the summary: title, period, sections covered, working days, reporting time, probation, notice period, benefits, safety. Repeat the notes about live settings and that this creates a draft only.
4. **Ask for confirmation.** "Shall I save this as a draft HR policy?"
5. **Call `commit_hr_policy`.** Tell the user it is saved as a draft, share the link to the HR Policy Studio, and explain they review, adjust and publish it there.

## Errors

- `ALREADY_EXISTS`: a policy with that title exists; choose a new title.
- `PREVIEW_NOT_FOUND_OR_EXPIRED` (15 minutes): preview again, confirm again.
- `PREVIEW_ALREADY_USED`: already saved; do not save again.
- `RATE_LIMITED`: daily limit reached; try again tomorrow or continue in the Studio.
- `NOT_AUTHORIZED`: only a company admin of the connected company can do this.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: create-sop
description: Generate a Standard Operating Procedure (SOP) or company-wide employee handbook from a company's KPI Gamification gamecards and HR Kits. Use when a company admin asks for an SOP, standard operating procedure, process document, handbook or escalation matrix for one or more roles. Previews first and saves a draft only after the user confirms. Needs at least one existing gamecard.
---

# Create an SOP

An SOP describes how work is done for the roles it covers: purpose, scope, roles involved, process steps, escalation matrix, tools and annexures. The server builds it from the company's gamecards (and HR Kits, if they exist) with KPI Gamification's own generator. You choose the category, the title and which roles it covers. It is free and saves a **draft**; no PDF is generated.

Tools: `list_gamecards`, `preview_sop`, `commit_sop`.

## Rules you never break

1. **Do not write the SOP yourself.** The content comes from the server. Do not present your own text as the saved document.
2. **Ask which roles and which category** instead of choosing for the user.
3. **Preview, show, confirm, commit.** Call `commit_sop` only after the user has seen the summary and clearly said yes. Fresh UUID `request_id` per commit; reuse it only to retry the same commit.
4. **Team Member, not Employee.**
5. You cannot publish or assign anything; the user finishes in KPI Gamification.

## Steps

1. **Call `list_gamecards`** to see what exists. If there are none, say an SOP needs a gamecard and offer the `create-game-card` skill.
2. **Choose the category** with the user. `category` is one of `company-wide`, `sales`, `marketing`, `operations`, `hr`, `finance`, `customer-service`, `it`, `other`. `company-wide` is the employee handbook for everybody (leave `gamecard_ids` empty to cover all roles). Every other category is a process SOP and needs at least one gamecard.
3. **Choose the roles** (`gamecard_ids`), up to 25, using ids from `list_gamecards`. Confirm the names with the user.
4. **Choose a title**, for example "Sales Process SOP". Propose one if the user has no preference.
5. **Call `preview_sop`.**
   - `valid: false`: read `errors` and their `fix`, correct, call again.
   - `valid: true`: show the summary: title, category, roles covered, purpose, process steps (as a numbered list), escalation rows, tools, annexures, and that a draft with serial `SOP-<year>-NNNN` will be created.
6. **Ask for confirmation.** "Shall I save this SOP as a draft?"
7. **Call `commit_sop`** with `preview_id` and a new `request_id`. Tell the user it is saved as a draft with its serial number, and share the link so they can review, edit and generate the PDF.

## Errors

- A gamecard not found: call `list_gamecards` again and use returned ids.
- `PREVIEW_NOT_FOUND_OR_EXPIRED` (15 minutes): preview again, confirm again.
- `PREVIEW_ALREADY_USED`: already saved; do not save again.
- `RATE_LIMITED`: daily limit reached; try again tomorrow or continue in the app.
- `NOT_AUTHORIZED`: only a company admin of the connected company can do this.

Referenced files: 1 — file references are metadata, not package contents.