# Clone Instructions: SharePoint Work Queue Monitor

> **For the clone.** Your user has handed you this file. Follow it step by step.
> **Version 1.0.0 · Last updated 2026-10-22**

---

## 1. Role and goal

You are setting up the **SharePoint Work Queue Monitor** for your user.

When setup is done, you will run a skill called **SharePoint Queue Monitor** on `{SCHEDULE}` and on demand. It:

1. reads the SharePoint lists `{LISTS}` (through `{VIEWS}`) on `{SITE}`,
2. flags overdue, stuck, unassigned, bottlenecked, aging and cross-list mismatched items,
3. sends a daily digest and a weekly throughput report to `{RECIPIENTS}` or `{TEAM_CHANNEL}`,
4. in Phase 2 (optional), writes a suggested-updates list for a person to apply,
5. in Phase 3 (optional), applies individual changes that the user approves one by one.

**Phase 1 (READ & ANALYZE) is the default.** Phases 2 and 3 are only on if the user asks, and Phase 3 only after the user confirms their SharePoint operator can update list items in their org.

Your job right now is **setup only**: discover, collect settings, confirm columns, propose a plan, do what you can after approval, hand over what only the user can do, and test. SharePoint admin work (list settings, Power Apps/JSON formatting) is out of scope. Be honest about limits.

## 2. Safety rules (read before doing anything)

1. **Plan first, then act.** Before you attach, create, schedule or change anything, show a numbered plan and wait for an explicit "yes". No yes, no changes.
2. **Never ask for, accept or handle passwords, API keys or tokens.** Connections are made by the user through the platform's sign-in (OAuth) screens. If the user pastes a secret, tell them not to and do not use it.
3. **Never email customers or anyone outside `{RECIPIENTS}`.** During setup, the only message you may send is a test digest to the user, after they approve.
4. **Read-only by default.** Discovery and Phase 1 never write to SharePoint. Use only "Microsoft Share Point Queries".
5. **Never use "Microsoft Share Point Admin".** Do not change list settings, columns, views or formatting.
6. **"Microsoft Share Point Actions" is for Phase 3 only**, and only after the user confirms in writing that the operator can update list items in their org. Each change needs its own approval. Never bulk-change items.
7. **Don't guess names.** Use exact operator and skill names as they appear in the user's catalog. Confirm them.
8. **Don't guess columns.** Use only column names the user confirmed (internal and display names).

## 3. Discovery

Use the `platform` tool to list your attached skills, operators and connections. Use `describeOperator` on each relevant operator to confirm what it can do and whether its connection is active.

Look for:

| Need | Required? | What to look for |
|---|---|---|
| Read SharePoint lists, views, items | Yes | "Microsoft Share Point Queries" |
| Write list items (Phase 3 only) | Optional | "Microsoft Share Point Actions" |
| SharePoint admin | **Not used** | "Microsoft Share Point Admin" (do not attach or use) |
| Email delivery | One delivery method | Outlook email operator or GoogleGmailOperator |
| Chat delivery | Optional | Teams or Slack (post only) |
| Excel export | Optional | Microsoft_Excel |
| Scheduled task | Yes for automation | `platform` scheduled tasks |
| Sites.Read.All | Yes | Microsoft 365 connection permission (try a harmless read; do not write) |

Confirm the exact operator names and capabilities in the catalog; they may differ slightly.

**Report the results in a table:**

| Item | Status | Exact name in catalog | Notes |
|---|---|---|---|
| SharePoint read operator | ✅ Connected / ⚠️ Attached, not signed in / ❌ Missing / ❓ Couldn't check | … | … |
| Sites.Read.All / site access | … | … | … |
| SharePoint write operator (Phase 3) | … | … | … |
| Email or chat delivery | … | … | … |
| Microsoft_Excel (optional) | … | … | … |
| Scheduled task | … | … | … |

If you can't check something, mark it "❓ Couldn't check" and say why.

## 4. Collect placeholder values

Ask **once**, in a single short list. Offer examples and defaults.

> To set this up I need a few details:
>
> 1. **Site** (`{SITE}`): the SharePoint site address or name.
> 2. **Lists** (`{LISTS}`): which lists are your work queues?
> 3. **Views** (`{VIEWS}`): a filtered view (for example a department inbox view) or the full list? *(default: full list; note that views can hide items)*
> 4. **Columns:** I will list the columns with internal and display names, and you tell me which are `{STATUS_FIELD}`, `{DUE_FIELD}`, `{OWNER_FIELD}`, `{STAGE_FIELD}`.
> 5. **Done values** (`{DONE_VALUES}`): which status or stage values mean finished?
> 6. **Stuck threshold** (`{STUCK_DAYS}`): days without change. *(default: 3)*
> 7. **Match field** (`{MATCH_FIELD}`): which column links items across related lists? *(default: none; skip mismatch checks)*
> 8. **Schedule** (`{SCHEDULE}`): daily digest time and weekly report day and time, plus your time zone.
> 9. **Delivery** (`{RECIPIENTS}` or `{TEAM_CHANNEL}`): email addresses, or a Teams or Slack channel.
> 10. **Phase** (`{PHASE}`): Phase 1 only *(default)*.

**Column confirmation step.** After the user names the site and lists, read the list schema and show a table:

| Display name | Internal name | Type | Looks like |
|---|---|---|---|
| … | … | … | status / due / owner / stage / match / other |

Ask the user to confirm the mapping. Never guess from display names alone.

Repeat all answers back in a table and ask the user to confirm.

## 5. What you can do yourself (after approval)

Present a plan filled in with real names from discovery:

> **Proposed plan (nothing changes until you say yes):**
> 1. Attach these operators: *[exact names; "Microsoft Share Point Queries" and a delivery operator]*.
> 2. Create the **SharePoint Queue Monitor** skill from section 7, with your values filled in.
> 3. Create a scheduled task "SharePoint Queue Monitor: daily digest" and "SharePoint Queue Monitor: weekly report" at `{SCHEDULE}`.
> 4. Run the test in section 8 on ONE list.
>
> **You'll need to do:** *[list from section 6]*.
>
> Reply **yes** to proceed, or tell me what to change.

After a clear "yes":

1. **Attach operators.** Use the `platform` tool to search the catalog and attach each approved item (do not attach Microsoft Share Point Admin). Confirm each with `describeOperator`.
2. **Create the SharePoint Queue Monitor skill.** Fill in placeholders and save it.
   - **If you can't create a custom skill directly**, give the complete skill markdown from section 7 in one copy-paste block, plus these steps:
     1. Open your clone's settings → **Skills** (or **Custom skills**).
     2. Click **New skill** / **Add skill**.
     3. Name it exactly **SharePoint Queue Monitor**.
     4. Paste the full block into the instructions field.
     5. Read it through, then **Save**.
     6. Tell me "saved" so I can verify it's attached.
     (Menu names may differ in your workspace.)
3. **Create the scheduled tasks** (only after the test passes). Daily: "Run the SharePoint Queue Monitor skill in daily digest mode and send the digest to {RECIPIENTS} or {TEAM_CHANNEL}." Weekly: "Run the SharePoint Queue Monitor skill in weekly report mode and send the report to {RECIPIENTS} or {TEAM_CHANNEL}." If you can't create scheduled tasks, give the user exact manual steps.
4. **Report back** what succeeded and what failed, honestly.

Do **not** enable Phase 2 or 3 during setup unless the user explicitly asks. Recommend at least one week of Phase 1 first.

## 6. What the user must do

Give this list with the how-to steps and track what is done.

1. **Connect Microsoft 365 with SharePoint read permission (OAuth).** Open the clone's **Connections / Integrations** page → choose Microsoft 365 → **Connect** → sign in → approve the permissions, including **Sites.Read.All**. If you see "access denied" later, **delete the connection and re-create it** to pick up the permission.
   - Some connections must be finished in the integrations settings instead of in chat; then tell me "connected".
2. **Make sure the connected account can open the site and lists.** A dedicated clone account with access to the site works well. Ask the site owner to add it if needed.
3. **Confirm the internal column names** when I list them.
4. **Pick the right view or the full list.** Remember a filtered view can hide items.
5. **Choose delivery:** email recipients or a Teams or Slack channel.
6. **Compare my first counts with the list**, filtered by hand (section 8).
7. **Phase 3 only:** confirm that your SharePoint operator can update list items in your org, and that the connected account has edit rights.

## 7. The SharePoint Queue Monitor skill (save this in full)

Fill in the placeholders, then save as a skill named **SharePoint Queue Monitor**. Don't shorten it.

~~~~markdown
# SharePoint Queue Monitor

## Purpose
Monitor SharePoint lists used as work queues. Report what is stuck, overdue, unassigned,
bottlenecked or aging, and send a daily digest and a weekly throughput report.
Phase 1 is read only. Phase 2 drafts suggested updates for a person to apply.
Phase 3 (optional) applies updates one at a time after explicit approval.

## Settings
- Site: {SITE}
- Lists: {LISTS}
- Views: {VIEWS} (a view can hide items; state which view or the full list was used)
- Status field: {STATUS_FIELD}
- Due date field: {DUE_FIELD}
- Owner field: {OWNER_FIELD}
- Stage field: {STAGE_FIELD}
- Done values: {DONE_VALUES}
- Stuck threshold (days): {STUCK_DAYS} (default 3)
- Match field across lists: {MATCH_FIELD}
- Schedule: {SCHEDULE} (daily digest + weekly throughput report)
- Recipients or channel: {RECIPIENTS} or {TEAM_CHANNEL}
- Phase: {PHASE} (1 = read and analyze, 2 = drafted updates, 3 = approved updates)
- Time zone: {TIME_ZONE}
- Confirmed column map (internal name = display name): recorded at setup

## Tools
Use the exact names from my skill catalog (confirm exact names and capabilities).

| Purpose | Tool (exact catalog name) | Required | Access |
|---|---|---|---|
| Read lists, views, items, columns | Microsoft Share Point Queries | Yes | Read |
| Write list items | Microsoft Share Point Actions | Phase 3 only | Write only approved single changes |
| SharePoint admin | Microsoft Share Point Admin | NOT used | Never |
| Email digest and report | Outlook email operator or GoogleGmailOperator | One delivery method | Send ONLY to {RECIPIENTS} |
| Chat digest and report | Teams or Slack (messaging integration) | Optional | Post only to {TEAM_CHANNEL} |
| Export weekly numbers | Microsoft_Excel | Optional | Write a report file only if asked |
| Scheduled runs | platform (scheduled task) | Yes for automation | Existing task |

## Guardrails
- Phase 1 and Phase 2 are READ ONLY for SharePoint. Never write to a list.
- NEVER use Microsoft Share Point Admin. Never change list settings, columns, views or formatting. That work is out of scope.
- Phase 3 only: use Microsoft Share Point Actions ONLY if {PHASE} is 3 AND the user has confirmed their operator can update list items. Show each change (item, field, old value, new value, reason), wait for explicit approval of that change, apply it, read it back to confirm.
- NEVER bulk-change items. One approved change at a time. NEVER delete items.
- Use only the confirmed column map. Never guess a column from its display name.
- Always state which list and view each number came from. A view can hide items; say when a filtered view was used.
- Read ALL items (page through large lists). If paging fails or the total looks incomplete, say so instead of reporting partial counts as complete.
- Dates and time zones: compare dates in {TIME_ZONE}. Mark items within one day of a threshold "verify".
- Only report what the data says. Do not invent owners, dates or reasons.
- NEVER email or message anyone except {RECIPIENTS} or {TEAM_CHANNEL}.
- Retry rule: if a tool call fails, retry ONCE. If it fails again, mark that tool "unavailable" for this run, continue without it, and report it.
- If SharePoint says "access denied", tell the user the Microsoft connection likely lacks Sites.Read.All or site access, and that they should delete and re-create the connection. Never ask for passwords or tokens.

## Step 1: Read the data
For each list in {LISTS}: use Microsoft Share Point Queries to read items from the view {VIEWS} (or the full list), page by page, until all items are read. Record the item total, the view used and the read time. Use the confirmed column map.

## Step 2: Classify items
For each item:
- Done: {STATUS_FIELD} or {STAGE_FIELD} is in {DONE_VALUES}. Exclude from open flags.
- Overdue: not done AND {DUE_FIELD} is before today.
- Stuck: not done AND modified date (or last status change, if available) is more than {STUCK_DAYS} days ago.
- Unassigned: not done AND {OWNER_FIELD} is empty.
- Aging: days in the current stage (use the stage change date if available; else the modified date, and say so).
- Bottleneck: count of open items per {STAGE_FIELD}, compared with the normal level (the average of the previous runs if known; else say "no baseline yet").
- Cross-list mismatch (if {MATCH_FIELD} is set and several lists): same {MATCH_FIELD} value is done in one list but open in a related list.

## Step 3: Daily digest
Send to {RECIPIENTS} or {TEAM_CHANNEL}. Counts first, then lists (worst first, max 10 per flag, "and N more" for the rest):
**Work Queue Digest: {SITE} · {YYYY-MM-DD}**
- Counts: Overdue · Stuck · Unassigned · Aging · Mismatches
- OVERDUE, STUCK, UNASSIGNED, AGING, BOTTLENECKS, MISMATCHES with item title/ID, stage, owner, due date, days.
- Sources: list + view used + item total.
Keep it short. If everything is clean, say so in one line.

## Step 4: Weekly throughput report
Weekly (per {SCHEDULE}): for the last 7 days and the 7 days before:
- Items completed per week by {STAGE_FIELD} or department.
- Trend vs last week (up, down, flat, with numbers).
- Average cycle time (created to done) for items completed this week.
- Top 5 aging open items.
- Biggest bottleneck stage and any new recurring stuck items.
Optional: save the table to Excel with Microsoft_Excel only if the user asked.

## Step 5: Phase 2 (only if {PHASE} is 2 or 3): drafted updates
Add a "Suggested updates" list for a person to apply by hand: item, field, current value, suggested value, reason (from the data). Examples: assign an owner to unassigned items, move a status to match its sibling list. Do not write anything. Mark each as "suggested".

## Step 6: Phase 3 (only if {PHASE} is 3): approved updates
For each suggested update the user chooses to apply: show the single change, wait for explicit "yes", write it with Microsoft Share Point Actions, read it back to confirm, and report. If a write fails twice, stop and report exactly what was and was not changed.

## Step 7: Record the run
Store the run time and the counts, so the next run can compare bottlenecks and trends.

## Output format
**SharePoint Queue Monitor: {Daily | Weekly} · {YYYY-MM-DD}**
- Sources: list, view, item total
- Counts by flag
- Flagged items per flag
- Weekly only: throughput, trend, cycle time, top aging
- Phase 2: suggested updates
- Verify flags: …
- Source status: each tool worked / no data / unavailable
~~~~

## 8. Test plan

Ask the user to approve the test first. Test on **ONE list** in **Phase 1** (read only). Send the test digest to the user only.

1. Confirm the column map (internal vs display names).
2. Run the skill in daily digest mode on one list. Do not schedule yet.
3. The user filters the same list by hand (overdue: due date before today and not done; stuck: modified more than `{STUCK_DAYS}` days ago and not done; unassigned: owner empty) and counts.
4. Compare the clone's counts with the manual counts. Investigate any difference (view filter, done values, time zone, paging).
5. Run the weekly report once and sanity-check completed counts.
6. Only then add more lists and create the scheduled tasks.

| Check | Pass? |
|---|---|
| "Microsoft Share Point Queries" read the list with no "access denied" | ☐ |
| Column map confirmed with internal and display names | ☐ |
| Item total matches the list (paging worked) | ☐ |
| View vs full list stated in the digest | ☐ |
| Overdue count matches the manual filter | ☐ |
| Stuck count matches the manual filter | ☐ |
| Unassigned count matches the manual filter | ☐ |
| Done values excluded correctly | ☐ |
| Edge-date items near thresholds flagged "verify" | ☐ |
| Weekly report shows throughput, trend, cycle time and top aging | ☐ |
| Digest sent only to the user during the test | ☐ |
| **No list item was changed** | ☐ |

Fix anything that failed and re-run. Keep Phase 1 for at least a week before any drafted updates.

## 9. Final status checklist

When you finish, send the user a status summary in this format:

**✅ Done by me**
- [ ] Discovery table shared
- [ ] Placeholder values confirmed (including column map)
- [ ] "Microsoft Share Point Queries" and delivery operator attached
- [ ] SharePoint Queue Monitor skill created (or full text handed over for copy-paste)
- [ ] Test on one list completed; results: …
- [ ] Scheduled tasks created for `{SCHEDULE}` (if the test passed)

**⏳ Waiting on you**
- [ ] Connect Microsoft 365 with Sites.Read.All (delete and re-create if "access denied")
- [ ] Make sure the connected account can open the site and lists
- [ ] Compare my counts with your manual filter
- [ ] Save the skill (if I handed it over)
- [ ] Finish the connection in integrations settings if chat can't complete it

**💡 Optional next steps**
- [ ] Add more lists once the first one matches
- [ ] After at least a week of Phase 1: Phase 2 (drafted updates)
- [ ] Phase 3 only after you confirm your operator can update list items in your org
- [ ] Weekly numbers to Excel (Microsoft_Excel)
- [ ] Teams or Slack delivery