Performance & appraisals

Your workspace has two related tools for measuring how people are doing:

• Appraisals — structured, periodic reviews built on a weighted competency template. Employees self-assess, managers rate, and HR finalizes a signed record (with a verification QR) that can optionally feed a pay increase into payroll.
• Performance tracking — a continuous, evidence-based scoring engine. It turns assigned tasks, daily reports, attendance, and connected GitHub / WHMCS activity into a merit score, and can recommend merit-based pay increments for you to review.

Both live under the admin menu. Employees see their own side under My Performance and Appraisals in the portal.

Throughout, one rule holds for anything money- or AI-related: the AI only proposes — a person always approves. No pay change is ever applied automatically.

---

Part 1 — Appraisals

Set your review rules first

Open Admin → Appraisals → Settings (/admin/appraisals/settings). Here you choose:

Setting	What it does
Default cadence	annual, half_yearly, quarterly, or custom — the suggested rhythm for new cycles.
Rating scale max	The top of the rating scale (a number from 2 to 10, e.g. a 1–5 scale).
Rating scale labels	Optional words for each rating (e.g. "Meets expectations").
Self review	Whether employees rate themselves before the manager.
Manager review	Whether the assigned reviewer rates the employee.
Peer review	Reserved for a later phase — not yet part of the review flow.
Auto-flow to payroll	When on, a finalized appraisal that recommends an increment creates a pending salary increment for approval (see below).

Build a competency template

Open Admin → Appraisals → Templates (/admin/appraisals/templates) and create a template. A template is a list of competencies, each with a weight, and the weights must add up to 100. For example: Quality of work 40, Communication 20, Ownership 20, Punctuality 20.

note

Once a template has been used by any cycle, you can still rename it and add competencies, but you cannot remove existing ones — that would break the historical record. Create a new template instead.

Run a cycle

A cycle is one round of appraisals for a period, pinned to a template.

1. Open Admin → Appraisals → Cycles (/admin/appraisals/cycles) and create a cycle: name, cadence, the period start/end dates, optional self- and manager-review due dates, and the template to use.
2. Use Roll out to generate one appraisal per employee. With no selection it covers every active employee; you can also target a specific list. Each employee's reviewer defaults to their reporting manager.
3. Rolling out activates the cycle and emails each new participant. Rolling out again later (for new hires) only adds and notifies the people who don't already have a row — no one gets pinged twice.

An appraisal moves through these stages:

pending → self_in_progress → self_done → manager_in_progress → manager_done → finalized

If self-review is turned off, it starts at the manager stage; if manager review is off, a submitted self-review jumps straight to manager_done.

• Employee self-review — the employee opens Portal → Appraisals (/portal/appraisals), rates each competency against the scale, adds comments, and submits.
• Manager review — the reviewer sees the appraisal in their review queue in the portal, rates each competency, and submits. HR is notified.

Finalize the record

When an appraisal reaches manager_done, an HR admin opens it (/admin/appraisals/:id) and finalizes it. On finalize the system:

• Computes the final rating as the weight-weighted average of the manager's competency ratings.
• Lets you add final comments and, optionally, a recommended increment (a percentage or a fixed amount) and a promotion recommendation to a new designation.
• Produces a finalized PDF stamped with a verification QR code. Anyone can scan it to confirm the document is genuine and untampered on the public verification page.
• Emails the employee with the signed PDF attached.

A finalized appraisal is locked — its cycle and reviews can no longer be edited.

Flowing an increment into payroll

If Auto-flow to payroll is on in settings and the finalized appraisal carries a recommended increment, the system creates a pending salary increment for that employee. It appears in the normal payroll Increments queue and still requires a human to approve it there — auto-flow never bypasses that approval. It is created once per appraisal, so re-finalizing won't duplicate it.

Appraisal emails

The cycle sends four automated emails, all editable in your email templates: cycle started, self-review submitted (to the reviewer), manager review submitted (to HR), and appraisal finalized (to the employee, with the PDF).

---

Part 2 — Performance tracking

The performance engine builds a merit score from real evidence rather than a single yearly form. It is designed so the score is hard to game and easy to explain.

How the score works

Every scored event writes a line to a merit evidence ledger. Each employee's score for a date range blends two things:

• Quality — of the points available, how many were actually earned (a ratio, so it isn't inflated by doing more).
• Volume — how much was earned versus what the role is expected to produce in that period.

Quality and volume are combined into a single composite score from 0 to 100, using the quality/volume weighting you set in performance settings.

Scorecard profiles

Open Admin → Performance → Scorecard profiles (/admin/performance/profiles). A profile decides, for a group of people, how much each evidence source counts and how much output is "expected." For example:

sourceWeights: { tasks: 0.6, daily_report: 0.1, attendance: 0.3 }
expectedMonthlyPoints: 100

Assign a profile to a designation or to an individual employee, and mark one profile as the default that applies when nothing more specific matches.

Tasks

Open Admin → Performance → Tasks (/admin/performance/tasks). Managers assign work here, and completed work becomes evidence:

1. Create a task with a title, assignee, due date, and priority.
2. The AI proposes a difficulty weight (points). The manager confirms or edits it, which activates the task.
3. The employee starts the task and marks it complete with a note (Portal → My Performance).
4. The manager grades quality 1–5. The AI turns that grade plus the completion note into a quality factor, and the earned points are recorded — quality × timeliness, with a bonus multiplier only for genuine off-day work.

The manager's rating is the anchor

The AI may only nudge the manager's rating by a small, hard-bounded amount (±0.15 of the rating-out-of-5). A terse completion note can never tank a well-rated task — many strong performers simply don't write prose. Timeliness is also floored at zero: finishing very late can earn nothing, but never subtracts points, so completing a task always beats abandoning it.

Recurring tasks (/admin/performance/recurring-tasks) are schedules — daily, weekly, or monthly — that automatically create the same task for a group. These are self-graded at full quality when completed on time; missing one records a negative signal.

Recurring schedules need company-wide rights

Because a schedule can target any employee, creating or editing one requires performance.manage or performance.view_all alongside performance.review. A team-scoped reviewer (see Who can do what) manages one-off tasks for their direct reports only, and the Recurring Tasks page is hidden from them.

Daily reports

If enabled in settings, employees file a short daily report. Submitting one earns the submitted-report value from settings, scaled by an AI quality verdict; a missed report on a working day records the missed-report penalty. All day boundaries — what counts as "today," the missed-report sweep, and the activity suggestions — follow the company's time zone, not the server's.

How the AI verdict works. The reviewer reads the report itself first, and treats tracked activity only as supporting evidence. It knows the employee's role, whether they have linked GitHub / WHMCS identities, and whether your company assigns performance tasks at all — so it never punishes people for work the system simply doesn't track. The four verdicts:

Verdict	Meaning	Points effect
ok	Says concretely what was worked on. It does not need to be long, and it does not need attached evidence — most legitimate work (meetings, ops, sales, admin) leaves no trace in the tracked systems.	Full value
low_effort	So vague a manager can't tell what was done ("worked all day"). Judged on information content, not length.	Half value
duplicate	Near-verbatim copy of the previous report. A genuinely repetitive job producing similar-shaped reports is not a duplicate.	Reduced
mismatch	Requires a positive contradiction: the employee has a linked identity, claims specific tracked work (e.g. "merged 3 PRs"), and the tracking disproves it. Absence of evidence is never a mismatch.	Lowest

A report the AI never graded (AI off or unavailable at submit time) is stored with no verdict — it earns full value and is never presented as an AI-cleared ok.

A wrong verdict is not final

Anyone with performance.manage can override a verdict from the Daily Reports page: pick the correct verdict on the report card and confirm. The employee's points are corrected through an appended ledger entry, the card shows an Overridden badge, and the AI's original verdict is kept for audit.

Submission rules. A report needs at least 20 characters of content. It can be filed for today or backfilled up to 7 days — filling in a day the sweep already marked missed reverses that penalty. Future dates are rejected, and once submitted, a day's report is locked.

You read submitted reports and their verdicts under Admin → Performance → Daily reports (/admin/performance/daily-reports). The reader is built for working through a period, not skimming a dump:

• Filters sit in their own card above the list: a From/To date range (defaults to roughly the last two weeks) with quick presets — 7/14/30 days, This month, and Last month — plus an employee picker covering the full active roster, a department filter, a status filter (submitted / missed), and a verdict filter. A Clear button appears whenever any of the non-date filters are set.
• The verdict filter's options are All verdicts, Any flagged, OK, Low effort, Duplicate, and Mismatch. Any flagged is a shortcut for any submitted report the AI did not clear — reports still awaiting a verdict are not counted as flagged.
• Summary chips above the results show the range's total plus flagged and missed counts. Those two counts deliberately cover the whole filtered range regardless of the status or verdict filter you've drilled into, so they stay meaningful while you inspect a single verdict — and each chip is clickable and applies the matching filter.
• Results are paginated: 50 rows per page by default, selectable between 25 / 50 / 100 / 200 (200 is also the server-side cap). Changing any filter resets you to page 1.

GitHub & WHMCS evidence

When your workspace connects the GitHub and WHMCS integrations, work done there feeds the same ledger automatically:

• GitHub — merged pull requests, code reviews (including AI-graded review quality on opted-in repos), and issues worked or closed.

• WHMCS — support-ticket replies, graded on the replying agent's own messages. Two things are scored, and they measure different things:

  • the first reply on a ticket, against your WHMCS first-response SLA, so speed counts;
  • each agent's replies per day, per ticket, worth the WHMCS reply credit from settings and scaled by the AI quality grade. Tickets that pass between people are ordinary support work, so everyone who worked one is scored — not only whoever happened to answer first. The first responder's own first day is covered by their first-reply row and is not counted twice.

  A day's replies are graded once that day has ended in your company's time zone, so an agent who comes back to a ticket after lunch is judged on the whole day rather than on however much of it existed when the hourly poll last ran. Set the reply credit to 0 to score first responses only.

This activity corroborates daily reports (so genuine work with a brief note still reads as ok) and adds to the merit evidence used for scoring and increment recommendations. Connecting the integrations, linking logins to employees, triaging AI-flagged reviews, and the WHMCS time-zone setting are covered in Integrations for performance.

Weekly sales report

For sales staff (matched by a department named like "sales"), the engine collects a mandatory, numbers-only weekly report — no prose, just the metrics you define. Configure the metrics, deadline weekday, and hour in performance settings; the default deadline is Friday 6 PM in the company's time zone. Submissions are read under Admin → Performance → Sales reports (/admin/performance/sales-reports). This report does not affect the merit score.

Missed weeks are marked by an hourly sweep that always targets the newest week whose deadline has passed — so a brief outage during the deadline window can't cause a week to be skipped. The pre-deadline reminder is only sent to people whose week has no submission yet.

The scoreboard

Admin → Performance → Scoreboard (/admin/performance/scoreboard) ranks everyone's composite score for a date range (defaulting to the trailing 30 days — the same window the employee sees on their own portal page, so both sides always read the same number). Click into an employee (/admin/performance/employees/:employeeId) to see the source-by-source breakdown behind their number. The scoreboard requires performance.view_all.

Merit-increment recommendations (AI proposes, you approve)

Open Admin → Performance → Increment recommendations (/admin/performance/increment-recommendations). This is the pay side of the engine:

1. Generate — for a chosen window (about six months by default), the engine gathers each eligible employee's evidence and composite score. People with under three months' tenure are skipped as too new to judge fairly.
2. The AI proposes a band (none, small, standard, or strong) and a percentage, with a written rationale citing the evidence. If AI scoring is off or unavailable, a transparent rule-based fallback produces the recommendation instead — recommendations are labelled with whether AI or the rule generated them.
3. You review each one and either Apply or Dismiss it. Applying routes through the normal payroll increment path — the same one used for any manual raise — so a person with the payroll salary-assignment permission is the one who commits it. Nothing is applied on its own.

warning

The AI never changes anyone's pay. It only drafts a recommendation for a human to accept, edit the percentage of, or throw away.

AI and the operator's key

The AI used for weighting tasks, grading quality, checking daily reports, grading GitHub reviews and WHMCS replies, and drafting increment recommendations runs on the platform operator's AI provider and key ("operator pays"). Your workspace controls the master AI scoring enabled switch, found in Admin → Performance → Settings under the AI section.

When the switch is off, no AI is used anywhere in performance scoring: daily reports go ungraded (full value, no verdict), task weights fall back to priority defaults, and GitHub / WHMCS work is scored on metadata and speed only. No report, review, or ticket text leaves the system. The same is true whenever no key is configured — every AI step has a deterministic fallback, and the module never depends on AI being available.

Performance settings

Admin → Performance → Settings (/admin/performance/settings) collects the tuning knobs: the review SLA hours (GitHub), the WHMCS first-response SLA hours and the WHMCS reply credit, the missed-report penalty and the separate submitted-report value (what a filed report is worth before its verdict — kept independent so softening the penalty doesn't erase the reward), the recurring-task miss penalty, task reminder offsets, the off-day multiplier, the quality/volume weighting, the daily-report toggle and extra recipient, the AI-scoring switch, and the full weekly-sales-report configuration.

---

Who can do what

Area	Permission
Manage appraisal templates, cycles, and finalize	appraisals.manage
Change appraisal settings	appraisals.configure
Submit a manager review	appraisals.review
View / submit your own appraisal	appraisals.view_own
Manage performance settings, profiles, recommendations; override report verdicts; triage flagged reviews, void scores, and link integration identities	performance.manage
See the scoreboard and all reports	performance.view_all
Assign and grade tasks — team-scoped: on its own, this reaches only your direct reports' tasks (with performance.manage or view_all it becomes company-wide)	performance.review
Manage recurring task schedules	performance.review plus performance.manage or performance.view_all
Apply an increment recommendation	payroll.salary_assign
Your own tasks, score, and reports	performance.view_own

What employees see

From Portal → My Performance (/portal/my-performance) an employee can view their own composite score and breakdown, start and complete assigned tasks, file their daily report (with suggested GitHub / WHMCS items to attach), and — if they're on the sales team — submit the weekly sales numbers. From Portal → Appraisals (/portal/appraisals) they complete self-reviews and, as a manager, their review queue.