collaboration-intelligence

Files (9)

• SKILL.md
• openai.yaml · agents/
• icon.svg · assets/
• maintenance.md · references/
• schema.md · references/
• sutando-bridges.md · references/
• lookup.py · scripts/
• notify_reviewers.py · scripts/
• roster_union.py · scripts/

SKILL.md (first lines)

# Collaboration Intelligence

Build a living, evidence-backed collaboration map. Treat it as a coordination aid, not an authority or surveillance profile.

## First run

**A freshly installed map is empty, and the Operating contract below does not bootstrap it.** Step 1 there says to load the quick-lookup index first — on a new install there is no index, so an agent queries nothing, reports a miss, learns nothing, and stays empty. It never errors. An unbootstrapped map and a working one are indistinguishable from outside, which is the failure mode this skill exists to fight, turned on itself.

So run this once, before relying on the contract.

**0. Decide whether this pass may bootstrap at all — before seeding and before sweeping.**

The test is per-pass, not per-agent: does *this* pass have a serving `channel_id`?

- **with** one → do not bootstrap. Not the sweep, and **not the seeding either**: soliciting or recording cross-provider identity links is itself collection, and doing it while serving an ordinary room task persists sensitive cross-room associations before any privacy check. Report and stop.
- **without** one (a maintenance pass, owner-tier, serving no channel) → proceed to step 1.

Do not shortcut this by source type. "Cron passes carry no `channel_id`" is **host-specific and was measured false**: one host had 153 cron tasks with zero `channel_id`, another had 3 of 3 carrying one. Read the pass you are in.

And do not read the gate as clearance. Measured: `gate(serving_channel_id=None, …)` returns **ALLOWED**, because the blacklist lookup misses and an empty blacklist permits — it fails **open**. That is an absence of jurisdiction, not a permission; the judgement stays yours.

**1. Seed the owner-stated identity map before sweeping. The sweep enriches it; it never substitutes for it.**

This ordering is measured, not stylistic. On a 7,810-file corpus the sweep produced immediately usable *room* knowledge — traffic ranking plus honest coverage flags — and, for *identities*, a schema-shaped pile: the top participant by traffic and **the owner themselves** both came back as bare unknown ids, because Discord headers carry no display name. Any heuristic of the form "high traffic ⇒ important human" would have misclassified the owner and a peer bot with identical confidence.

Worse for derivation: a known cross-provider identity — one person holding a GitHub handle and a chat id whose display name collides with someone else's — was **underivable from that corpus at any confidence**. It existed in the map only as an owner-stated seed with provenance. That is what makes "owner-stated outranks derived" load-bearing rather than decorative.

So: ask for a handful of mappings (GitHub handle ↔ chat id ↔ person) before sweeping. It is the highest-value minute available, and it is the part the sweep structurally cannot do for you.

**The unresolved list is per-host, and so is the seed list.** The store is host-local by design (`data/` is outside the default vault sync set), so one machine's unknowns are not another's — two agents comparing notes found a Discord id that was authoritative on one host and absent from the other's config entirely. Do not ask someone else to enumerate your unknowns, and do not assume theirs are yours.

**2. Then sweep the task-file stream.** Step 0 has already established that this pass may do so.

> **The bootstrap is not permission-free, and "the bytes are already on disk" is not the test.** The context boundary is *serving-relative*: `src/discord_context_policy.py`'s `gate()` decides whether the channel you are **currently serving** may read some other channel, and it applies to owner-tier tasks too. Its fail-closed behaviour is **conditional**: it refuses an unresolvable guild only when the serving channel has a `contextNotFrom` blacklist at all — with no blacklist it returns ALLOWED before reaching that check (see the measured note above). So the boundary constrains a sweep only where someone configured it; elsewhere the judgement is yours. A sweep run while serving one channel would pull rooms that gate would have refused — and because the sweep **persists** what it reads, those rooms then inform every later answer. That is strictly worse than a single blocked read.
>
> So: run the bootstrap from an explicit owner/operator maintenance context, not as a side effect of handling a task. If you cannot establish that context, either filter every archived observation through the same serving-channel policy, or do not sweep. Record `access_scope` on each observation so a later answer cannot quietly widen it.

**Header fields are source-specific — check, do not assume.** Writers differ, and the richest one is not representative:

| source | provides | consequence |
|---|---|---|
| AG2 Space / Matrix | `channel_id`, `room_name`, `room_members`, `room_member_count`, `user_id` | rooms, names and rosters available |
| Discord | `channel_id`, `channel_name`, `guild_name`, `user_id` | **no roster, no member count** — membership is `unknown`, not empty |
| Slack | `channel_id`, `user_id` | id and speaker only; name and roster `unknown` |

Treat a field the source never emits as **`unknown`**, never as absent-therefore-zero — a room with no roster field is not a room with no members. Set `coverage: unknown` for those sources and `coverage: partial` only where a roster was truncated (`+N more`), which is recordable **at sweep time** and unrecoverable afterwards.

What the sweep yields, on the sources that carry it:

- **rooms**, ranked by traffic, with provider-native ids and whatever name the source gave
- **participants**, ranked by messages, classified `human` / `agent` / `service`
- **unknowns worth resolving immediately** — rooms with real traffic but no name and no members observed

Record the result per [references/schema.md](references/schema.md), including `store_freshness` per source. Do not enumerate rooms, inboxes or accounts you were not already given.

**3. Expect the sweep to surface defects, and record them rather than smoothing them.** Run against a real corpus it immediately produced unnamed high-traffic rooms, hundreds of truncated rosters, and a service account misfiled as human by a two-way agent/human split. Each is a real map entry — an unknown to resolve, a partial-coverage flag, a classification gap — not noise to filter out.

**4. Then let the scheduled work maintain it.** Only once the map holds something does the contract's load-first path mean anything.

**Validate the sweep against itself before trusting its counts.** A parsing sweep does not fail with an error; it returns a plausible number. One real attempt reported a tidy count of unresolved identities that was pure artifact — a fixed-size read had cut header lines mid-value, so a single identity appeared three times truncated to different lengths. A second attempt broke the opposite way and under-counted. Both looked normal.

So run two controls on your own output, and treat the sweep as unusable until both hold:

- **negative** — a known-bad artifact must be ABSENT (no truncated or prefix-duplicated identifiers).
- **positive** — a known-present, high-frequency participant (the owner, typically) must appear with a plausible magnitude. A parser that silently drops most records still returns a small, tidy, wrong set.

A count with neither control is an assertion, not a measurement.

**When the bootstrap is unreachable — say so and route it, do not quietly skip or quietly run it.**

The per-pass test lives at **step 0** above and gates seeding as well as sweeping. This section covers the case where the bootstrap cannot run at all.

- **A bundled install.** No `.git`, so the skill cannot be pulled or refreshed — a property of the packaging, not a choice available to the agent.

**You will not perceive this block. You have to go looking for it.** `skills/install.sh` iterates `$SKILLS_DIR/*/` — only directories that exist — so a skill absent from the bundle is never in the loop, `set -e` never trips, and the script ends by printing an affirmative claim:

```
Installed. Skills available in any Claude Code session.
```

Measured on a bundled host: that line printed for 60 skills while this one was in none of them. So the bundled case is not "cannot comply and knows it" — it is **cannot comply and cannot tell**, and an exit code of 0 with a success message is the evidence you would otherwise have trusted.

**So verify the destination, not the installer.** After installing, assert that this skill's own directory exists under the resolved skills root. Only that answer distinguishes the two cases; the installer's output cannot.

Having established a block that way, **report it to the owner/operator and stop**, rather than approximating compliance. An agent that judges its own context is the only thing currently enforcing this boundary, which is a weak place to put a privacy rule: prose does not fail because someone ignores it, it fails because *an instruction to cross it can look exactly like ordinary diligence*. That happened here — a request to "actually run it, not just read it" was well-intentioned and would have crossed the boundary within minutes of its landing.

If this ever needs a mechanical guard rather than a rule, the repo already has the shape: `discord-read.py` distinguishes a task-serving invocation from an operator one with an explicit `--operator` flag, and refuses rather than inferring.

**The payoff to check for**: after step 1 you should be able to answer "who is in this room, and which of them are agents" and "where does this kind of work usually get discussed" without asking anyone. If you cannot, either the sweep did not run or its store did not persist — see **Where the map is stored**.

## Trigger behavior

When triggered implicitly:

1. Identify the trigger: room observation, identity resolution, roster maintenance, unfamiliar participant, or collaboration routing.
2. Load only the existing records and bridge notes needed for that trigger.
3. Update the map when new evidence is present; otherwise use the map without manufacturing a change.
4. Keep routine bookkeeping silent. Surface only unknown identities, conflicts, stale facts, scope risks, or collaboration recommendations that affect the task.

Do not scan every connected service merely because the skill triggered. Expand to another room or provider only when the current task requires it.

## Firing without being asked

A skill description is matched against how you *framed* the task, and that is exactly what fails. Measured: the description already named coordinating, delegating and escalating work to a person or agent when an agent went to recruit PR reviewers — the case it covers — and it did not fire, because the agent had named the task "chase reviewers" (an action it already knew how to perform) rather than "choose collaborators" (a decision needing a map). Adding trigger phrases does not fix that; a re-framed task evades any phrase list, and the front-matter budget is finite anyway — 1024 characters, which a phrase list burns fast.

So do not rely on description matching alone. **Hook invocation to observable state, which does not depend on how anything was framed.** Each of these is a computed fact some routine already produces:

| Observable state | Why it is a collaboration-intent signal |
|---|---|
| A merge gate reports a PR queued on nobody, or on nobody who can act | "Assigned to no one" is indistinguishable from "waiting on review" in every UI. Only the gate can tell them apart. |
| Approvals present but fewer than the branch rule requires | The gap is arithmetic, not intuition — who closes it is the map's question. |
| An approval exists but is stale against the current head | The tick is real and describes a head nobody reviewed; someone specific must be re-asked. |
| An identity appears that no stable ID in the map resolves | Resolve before addressing, never after. |
| A request is about to go out addressed to nobody | Publishing is fine unaddressed; asking is not. |

The rule to carry: **when a routine you are already running computes one of these, invoke this skill from that routine** — as a step, not as a hope that the description matches. A step executes regardless of framing; a description does not. Bound it to once per (subject, state-change) so a standing gap does not re-fire on every pass.

The same measurement makes the weaker path explicit, and it is worth stating plainly rather than implying the trigger is solved: on the night this was written, the gate had *already printed* the queued-on-nobody verdict before the agent acted, and the agent still did not invoke the skill. A signal nothing is obliged to read changes nothing.

From sonichi/sutando, MIT.

More from sonichi/sutando