check-aw-desk - SKILL.md Agent Skill

name: check-aw-desk description: >- Check the Admireworks client desk (desk.admireworks.com) for a client's open requests, read the full thread, mark a ticket in-progress (which notifies the client), then map the request to the right repo and prepare an end-to-end fix plan. Trigger whenever the user says "check the desk", "check the AW desk", "check Admireworks desk", "anything on the desk", asks to work a desk ticket / desk request for a client, OR references a ticket by its reference code (an "AWD-XXXX" code, e.g. "AWD-7F3K", "what's AWD-9K2M", "look at ticket AWD-..."). A pasted AWD code resolves straight to the ticket and its client, so read it with read-desk.mjs --code. Standing default (under the user's authorization): act as an Admireworks team member end-to-end, investigate, fix and verify, then reply and clarify directly on the desk in the client's own dialect (run through arabic-copy-review), creating or updating tickets so the client is notified. Pause only for changes that are hard to reverse, costly, or security-sensitive. allowed-tools: Bash, Read, Edit, Write

Check AW Desk

The desk at desk.admireworks.com is where AW clients post issues, ideas, questions, and requests. Tickets live in Firestore (desk_tickets) on project admireworks---internal-os, shared with the portal (my.admireworks.com) which owns the write + notification logic. This skill reads a client's desk, marks a ticket in-progress (so the client is notified we are on it), maps the request to the repo that owns the affected surface, and prepares an end-to-end fix.

Full data model, notification mechanics, and the client registry: references/desk-data-model.md.

Act as an Admireworks team member (standing default)

When the user asks you to handle the desk (or a specific ticket / client issue), the default is to ACT AS A MEMBER OF THE AW TEAM, not as an outside assistant (Fouad's directive, 2026-06-20):

Own it end-to-end: investigate, fix it in the right repo, verify it live, then communicate the outcome on the desk yourself. Do not stop at a "here are options" hand-off.
Reply and clarify directly on the desk. Post the reply/clarification on the ticket so the client is notified: create a new ticket when the issue is not yet on the desk, reply on the existing one when it is. Speak as "we" / "احنا" (the AW team), warm Egyptian for Basseqat/Khaled and the relevant dialect otherwise, always non-technical and easy to read. Run every Arabic reply through arabic-copy-review.
Fix-first, then reply. Never tell a client something is fixed before it is shipped and verified. If it is a misunderstanding or a self-serve step, clarify it and tell them how to do it themselves. If it is a real build that is not done yet, say so honestly (acknowledged + in progress), do not claim it is done.
Pause only for the genuinely sensitive: changes that are hard to reverse, cost money, touch billing, or change security rules / permissions. Confirm those with the user first. Everything else, do it and report.

This refines the cautious step-by-step flow below: the "PAUSE / hand the draft to the user" defaults apply to sensitive changes; routine fixes and replies are done directly as the AW team.

When to use

Trigger on: "check the desk", "check the AW desk / Admireworks desk", "anything on the desk (for )", "work the desk ticket about X", a pasted ticket reference code (AWD-XXXX, e.g. "AWD-7F3K"), or any request to action something a client raised on desk.admireworks.com.

Every ticket carries a short, opaque, globally-unique reference code like AWD-7F3K (shown to both staff and the client on the ticket). When the user references one, skip the "which client?" step: the code resolves directly to the ticket and its client.

cd "Admireworks Internal OS"
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/firebase/service-account.json"
node .claude/skills/check-aw-desk/scripts/read-desk.mjs --code AWD-7F3K

Workflow

Identify the ticket. If the user pasted an AWD-XXXX code, skip ahead: it resolves directly to the ticket and its client. Otherwise ask which client first (the desk spans the whole portfolio); map the answer to a clientId via the registry (the reader accepts name / slug / prefix / clientId).

Read the open tickets (read-only). From the repo root:

cd "Admireworks Internal OS"
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/firebase/service-account.json"
node .claude/skills/check-aw-desk/scripts/read-desk.mjs --client "<name>"
node .claude/skills/check-aw-desk/scripts/read-desk.mjs --code AWD-7F3K     # by reference code
node .claude/skills/check-aw-desk/scripts/read-desk.mjs --id <ticketId>     # full one-ticket thread

--code and --id both print the ticket's code and resolved client up top. Read the messages, events, and attachments. For image / voice / video attachments, fetch the URL and analyze first-party (Read for images, Vertex for audio/video) before concluding what was asked.

Decide: actionable, or needs-info?
- If the request is clear enough to act on, continue to step 4.
- If it is underspecified (you cannot confidently decide what to build), do NOT guess. Draft the exact clarifying questions and show them to the user. On the user's OK, post them on the SAME desk thread and move the ticket to waiting_on_client (which emails + WhatsApps the client a link):
```
node .claude/skills/check-aw-desk/scripts/post-reply.mjs \
  --id <ticketId> --message "<question in the client's dialect>" --wait-client
```
  Write the question in the client's language (Egyptian Arabic for Khaled / Basseqat); run it through the arabic-copy-review skill first.
Mark in-progress (notifies the client). This sends a clean, linked "We are on it" email (Arabic when the ticket is ar) + web-push + WhatsApp where eligible:
```
node .claude/skills/check-aw-desk/scripts/set-status.mjs --id <ticketId>
```
These desk emails are NOT enrolled in the customer-success reply-chaser (see the email-misfire fix in the reference), so no confusing nudge follows.
Map to the repo + prepare an end-to-end plan. Identify which project owns the affected surface (use the global CLAUDE.md project table + the client-data-sources skill). The shared /admin/insights dashboard is sourced from the aw-email monorepo and propagated as a vendored tgz, not edited in the client repo. Write a concise plan: root cause, the files to change, how to ship, and how to verify.
PAUSE for go-ahead. Present the plan and stop before changing client code or shipping. The user approves, then you execute end-to-end (fix, deploy, verify) following the project's own deploy rules.
Draft the suggested client reply. After the fix is verified, write a short reply in the client's own dialect that (a) confirms what was done, (b) explains in plain language what the issue was, and (c) says how to verify. Run it through the arabic-copy-review skill first. Default: hand the draft to the user to send manually. Only post it on the thread (post-reply.mjs --id <id> --message "...") when the user explicitly says to. Before handing it over, confirm the requester is listed in the ticket's clientRecipients (the read dump shows this) so they get the resolve + reply notifications; if missing, flag it.

Reply style (AW house style, learned from AWD-JENM 2026-06-15). Match how AW actually sends, so the draft goes out with little editing:
- Greeting: أهلا أستاذة {name}، (warm but professional). Avoid very colloquial openers like هلا وغلا.
- Say only what was done and how it works now. Do NOT proactively offer extra features or future options the client did not ask for (the Tier-3 "we can make it show to parents / نرتبها لكم" line was cut on send).
- No formulaic sign-off (أنا بالخدمة, أي ملاحظة ثانية, نتشرف بخدمتكم). End on the substantive line.
- Keep it tight: cut parentheticals that could be inaccurate (the "official school email" aside was removed, only the WhatsApp number kept) and small fillers (عندكم).
Resolve is manual. Do NOT mark a ticket resolved on your own. After the fix is verified and the reply is sent, tell the user it is ready and let them resolve it (or ask explicitly). If asked, set-status.mjs --id <id> --status resolved --summary "...".

Asana-to-Desk mirroring (standard process)

Default for any client issue that arrives via Asana (or any internal tracker) and maps to a Desk-class request: Desk is the system of record for client communication; Asana only points to it. Standing process as of 2026-06-17 (Fouad's directive).

Fix + verify first. Do the work and confirm it live before telling the client anything.
Document on Desk, client-visible, on behalf of the client. One ticket per issue via /api/desk/create (visibility:'client', language matching the client, recipient = the client contact). Opening message in the client's own words (what they reported); a staff reply in AW house style stating what was done and how to verify. Use scripts/create-fis-desk-tickets.mjs as the template for the create + reply + resolve sequence. Run all Arabic through the arabic-copy-review skill in the client's dialect.
Resolve as part of close-out. For documenting completed work, marking the ticket resolved (which notifies the client) IS the standard here, under the user's standing authorization. This refines step 8 above, which still holds for open / in-flight tickets you should not pre-emptively resolve.
Point Asana at Desk. On each Asana task, post a short comment with the AWD-XXXX code plus desk.admireworks.com, then mark the task done (set the Status field to Completed). Do NOT duplicate the full write-up on Asana. Keep technical / root-cause detail as Desk --internal notes or on Asana; the client-visible Desk message stays plain-language.

Async dependency: keep an OPEN ticket + monitor

When the fix waits on an external approval (a WhatsApp template pending at Meta, a DNS change, a third-party review): create a SEPARATE Desk ticket, set it in_progress (we are working on it / awaiting approval, not waiting_on_client), and put the pending artifact's content inside the ticket so both teams see exactly what is coming. Then schedule a recurring check (the schedule skill) that resolves the ticket and notifies the client the moment the dependency lands, then removes itself. First use: FIS template visit_schedule_request_ar, ticket AWD-HZPZ, watcher fis-visit-template-approval-watch (2026-06-17).

Scripts

scripts/read-desk.mjs : read-only ticket dump (by client, by one --id, or by --code AWD-XXXX). Single-ticket dumps print the code + resolved client.
scripts/set-status.mjs : set status via the portal API + full notification fan-out (defaults to in_progress). Address by --code or --id.
scripts/post-reply.mjs : post a staff reply on the thread; --wait-client also sets waiting_on_client (for the needs-info branch). --internal for a staff-only note. Address by --code or --id.
scripts/_lib.mjs : shared helpers (client resolve, code resolve, staff-token mint).
scripts/create-fis-desk-tickets.mjs : reference template for the log-on-behalf + reply + resolve sequence (create one client-visible ticket per issue). Copy it per client; it is the canonical example for the Asana-to-Desk mirroring process above.

All scripts use the AW Internal OS service account and act as a staff user (fnasr@admireworks.com by default; override with --staff).

Notes

Reads are safe; writes (status, reply) notify the client immediately, so only run steps 3b/4 once you mean it.
Service account: Admireworks Internal OS/firebase/service-account.json.
First real use: Basseqat ticket 52a2i1NACPIOb1AMcaZA ("add a Today timeframe in insights"), 2026-06-06, which also surfaced + fixed the desk follow-up email misfire.
Second use: FIS Schools ticket AWD-JENM (qQMqqqZffQJFSW3JgXbz, "Adding a name"), 2026-06-15, which added the suggested-reply step (#7) to this flow: plan, user approves, execute end-to-end, then hand the user a ready-to-send client reply.

Cross-references

references/desk-data-model.md (collections, statuses, notification paths).
client-data-sources and check-whatsapp-client-messages skills (other client-feedback channels).
arabic-copy-review skill (use before posting any Arabic reply to a client).