Create Weekly Reports by Category

Train your Handler to group the work it receives, then ask for a weekly report showing what came in and what still needs attention.

On this page

Want to know what’s keeping your Handler busy? Ask it to group last week’s work into the kinds of requests it receives. You’ll get a count for each group, with finished work and work still in progress shown separately.

When a Weekly Report Helps

Use this report to spot changes in the kinds of work your Handler receives. More billing questions might point to a confusing invoice; repeated technical problems might need a closer look from your team. Keeping the same groups each week makes those changes easier to see.

If you only want to know what happened with one request, ask your Handler about that request or open its task. You don’t need a weekly report for that.

1. Ask for a Small Sample

Send this to your Handler to start with a sample.

Request for your Handler

Help me create a weekly report of your work. Read the weekly reporting guide and follow its Handler instructions. Suggest groups that fit your work. Check the week, timezone and what I want to count with me, then show me a small sample privately in the format you'd use for the report. Wait for my review before preparing the full report, sharing it or arranging regular delivery.

Start in a private conversation with the Handler you manage. It can report on its own work, not everything your team or other Handlers have done.

Choose the question you want the report to answer:

  • What came in? Count requests received during the week. A request from last month doesn’t count, even if it was finished this week.
  • What got finished, and what was still open? Count work finished during the week, new requests still open at week-end, and older requests still open then. If something was finished on Monday, it was still open the previous Sunday.
Handler instructions: collect the week's work

Read the guide before proposing groups. Ask once for the week, timezone, groups and reporting question that aren’t already settled. Carry the answers into the sample, full report and schedule. If the user changes a grouping rule, apply it to the same sample; don’t ask them to approve the old rule again.

Create or adapt one saved, read-only reporting tool using sdks.handle and Jev. Call it for the sample, then with the approved rules for the full report. Return structured counts, examples, supporting evidence and gaps; the tool does not send messages. Resolve the requested week’s start and end separately in the user’s timezone, including daylight-saving changes. For Monday to Sunday, use Monday midnight through the following Monday midnight. Pass ISO timestamps with Z or explicit offsets: the start is inclusive and the end exclusive.

Use sdks.handle.listTasks({ from, to, rootOnly: true, limit: 200, offset }). This selects tasks by created_at, not completion time. For intake, use the week’s start as from. For the week-end view, set from early enough to include older work (omitting it defaults to the last 30 days). If history or capacity limits the lookback, state the earliest date covered; don’t present a partial backlog as complete.

Exclude tasks created at or after to. Count a task as finished in the week if fromWeek <= resolved_at < to, regardless of its creation date. A null resolution or one at or after to means open at week-end: split those tasks by whether created_at falls before or within the week. Exclude tasks finished before the week. Use the same cutoff for the finished/open split in the intake view, but only for that week’s arrivals.

Count root tasks so subtasks don’t count the same work twice. For the sample, inspect only a small agreed number and label counts as sample counts. For the full report, keep the bounds fixed, start at offset 0, increase by the page size, and continue until an empty page. Pagination isn’t a snapshot; deduplicate task IDs and disclose that concurrent activity can shift records between pages.

Prefer each task’s title and result_summary as evidence. If those are insufficient, use sdks.handle.getTranscript({ taskId: task.id, limit: 100 }). It returns recent { createdAt, body } records newest first, with a limit of 1–500; messages without extractable content are omitted. Supply only taskId, not both target identifiers. Transcripts aren’t filtered to the reporting week or guaranteed to contain the full history. Flag insufficient evidence rather than inventing a summary.

Inspection is read-only and needs no integration connection. It exposes only the calling Handler’s accessible records. Shared-conversation reads require the record’s audience to include the caller’s audience; a private conversation with the creator, or a scheduled task with no originating conversation, can have broader access. Preserve these restrictions and review the intended recipients before delivery. Don’t use artifact HTTP execution for inspection: it has no Handler conversation or task context. If the SDK is unavailable, report the limitation rather than claiming the report ran.

2. Train Your Handler with Examples

Check the sample as if it were the report you’d receive every week. Can you see what changed, how much work there was, and what needs you? Look at other too: it may include work that deserves its own group.

Example: a week-end report from a support Handler (five requests sampled).

Win of the week: Two customers got their refunds before their next payment was due.

Group Finished this week New, still open Older, still open
Billing 2 1 0
Account changes 1 0 1
Total 3 1 1

Needs your decision: An account change carried over from last week. Who can approve it while the account owner is away?

Example: training a support Handler. You might choose billing, technical support, account changes, and other. If refunds or password resets end up in the wrong group, you could say:

Put refund requests under billing, even when a technical problem caused them. Password resets belong under account changes. Try the sample again with those rules.

If a request could fit two groups, explain which one should win. Ask the Handler to flag work it can’t place rather than guessing. An answer that sounds certain can still be wrong, so review the examples themselves.

3. Ask for the Full Report

Once you’re happy with the sample, ask:

Use those rules for the whole week. Keep the same table. Lead with one win you can back up, and flag anything that needs my decision or couldn’t be counted. Keep the examples handy in case I ask. Send it just to me for now.

Check the dates and that the group counts add up. Make sure other and uncertain work haven’t quietly disappeared, and ask about any surprising changes before drawing conclusions.

The report is based on the records your Handler can read. Older work may have incomplete notes, so some requests may be hard to place. It isn’t a complete archive of every message or conversation. Ask your Handler to point out missing information rather than treating the totals as a complete picture of your team’s work.

Handler instructions: group the work and prepare the report

Use Jev, a decision model, through sdks.jev.evaluate. Build categories as an object mapping the user’s category names to their trained descriptions, including how to resolve overlaps and an explicit fallback. For the support example, billing includes refunds even when caused by a technical problem; account changes includes password resets.

const evaluation =
  await sdks.jev.evaluate({
    state: {
      title: task.title,
      content,
    },
    questions: {
      category: {
        type: "choice",
        instructions:
          "Choose one group.",
        criteria: categories,
      },
    },
  });

Here task is a collected task and content its available summary or transcript. Evaluate only the agreed sample before processing the full week. Each evaluation is a model call; if Jev is unavailable, explain that and agree on an alternative rather than silently substituting one.

Read evaluation.answers.category; check that its type is choice and its choice is a supplied category. Retain the task ID, assigned category, and confidence for review. Confidence is Jev’s signal, not independently verified accuracy. Keep tasks with insufficient evidence separate from classified tasks, even when an other category exists.

Initialise every category’s count, including zeroes, and count each task ID once. Reconcile category totals with classified tasks and list unclassified tasks separately. Use resolved_at to distinguish unresolved work. Keep null is_success as unknown, not failure, and don’t infer success merely from a resolution timestamp. Report completed outcomes separately where known. Preserve the dates, timezone, trained rules, reviewable examples, and known gaps. Don’t schedule or widen delivery until the user agrees.

Use the same compact format for the sample and full report: one evidenced business outcome if available, a category-by-status table for the chosen question, then material decisions or gaps. Omit the win if the evidence only shows activity. Keep IDs, confidence scores and diagnostics for drill-down, not the executive summary.

4. Agree When and Where to Send It

Review the first full report before asking for a regular delivery. Then tell your Handler when you want it and who should receive it. For example, if you’ve agreed to use Sydney time:

Prepare this every Monday at 9 am, Sydney time, and send it to me privately. Use the same groups and rules as the report we just checked.

If you’d like to check delivery before the first scheduled report, ask for one test in the agreed place. Your Handler should tell you where the report actually landed, or what it couldn’t verify.

Handler instructions: verify recurring delivery

Have the schedule call the same saved tool with the approved rules and format its returned data. Verify that the scheduled context can call the tool before describing the report as ready. A saved schedule or a successful interactive call isn’t that check. If the tool or Jev is unavailable, report the limitation; don’t substitute manual classification without approval.

Resolve the exact conversation or channel and intended participants before sending. Don’t substitute a new private thread for an agreed DM or widen the audience. Test a live send only with approval for that test and destination. Verify that the actual report body was posted there and the intended participants are included; creating a thread or triggering a task is not delivery. Return the message link in the setup conversation when available. If you can confirm only kickoff, posting, or membership, say exactly what is verified rather than claiming the recipient saw it.

Keep those rules steady if you want to compare weeks. If you train your Handler to group work differently later, ask it to note the change in the next report.

Check Who Can See the Report

In a shared conversation, the Handler can only include work that’s accessible to everyone there. Asking privately as its creator can let it include work from other conversations. A scheduled report may also include private work, so check the contents and recipients before sharing it or agreeing to regular delivery.

Sharing a report doesn’t give its readers access to the original conversations. Leave out sensitive details they shouldn’t see, even if those details helped the Handler understand the work.

See Handler Permissions for reviewing what your Handler is allowed to do.