/gap-surfacer

name: gap-surfacer
description: >
  Reference: shared gap- and comment-tracker framework backing /regulatory-legal:gaps
  and /regulatory-legal:comments. Tracks open policy gaps with remediation status,
  ingests gaps from policy-diff, surfaces what's open and aging, routes to owners,
  and notifies gap owners via Slack with per-send confirmation. Loaded by the gaps
  and comments skills before doing substantive work.
user-invocable: false

Gap Surfacer

> Owner notifications: on by default. To opt an owner out, leave `owner_slack` empty.

Per-send confirmation — no exceptions

Before sending ANY Slack message (assignment notice, overdue reminder, bulk notification, status report):

1. Show the user exactly what you're about to send and to whom: "I'm about to send this to [N] people: [preview]." 2. Wait for an explicit yes. 3. If the message contains any citations, deadlines, or compliance conclusions, add: "⚠️ The citations in this message are unverified — I'm not confirming they're current before sending. Do you want me to add a 'verify before acting' line?" 4. Never send without the confirm. Not on a cadence. Not in a batch. Not because it was sent yesterday.

Auto-send without confirmation is the most irreversible action in this plugin, sending content this plugin's own footer says may be wrong, to people who have no way to check. That combination does not get to skip review.

Matter context

**Matter context.** Check `## Matter workspaces` in the practice-level CLAUDE.md. If `Enabled` is `✗` (the default for in-house users), skip the rest of this paragraph — skills use practice-level context and the matter machinery is invisible. If enabled and there is no active matter, ask: "Which matter is this for? Run `/regulatory-legal:matter-workspace switch <slug>` or say `practice-level`." Load the active matter's `matter.md` for matter-specific context and overrides. Write outputs to the matter folder at `~/.claude/plugins/config/claude-for-legal/regulatory-legal/matters/<matter-slug>/`. Never read another matter's files unless `Cross-matter context` is `on`.

---

Purpose

Gaps get found and then forgotten. This skill tracks them until they're closed and notifies the people responsible for closing them.

The tracker

Lives at `~/.claude/plugins/config/claude-for-legal/regulatory-legal/gap-tracker.yaml`:

> **Note on comment-tracker.yaml:** `~/.claude/plugins/config/claude-for-legal/regulatory-legal/comment-tracker.yaml` is a sibling file owned by the comments skill. It is written to by reg-feed-watcher (which logs NPRMs automatically) and the comments skill (which tracks user-initiated comment decisions). This skill does not read or cross-reference it. If you modify the comment-tracker schema, update both actual consumers.

gaps:
  - id: GAP-001
    requirement: "[what the reg requires]"
    regulation: "[name + cite]"
    policy_affected: "[name or 'new policy needed']"
    gap_type: "partial"  # none | partial | full | new-policy | watch | comment-decision
    owner: "[name from policy index]"
    owner_slack: "[Slack user ID or handle, if known]"
    opened: 2026-03-01
    due: 2026-06-01  # reg effective date, internal deadline, or comment deadline
    status_verified: true  # false if upstream policy-diff could not confirm the rule is in force; unverified items never hit 🔴 Overdue
    status: "open"  # open | in-progress | closed | risk-accepted
    notified: false  # set to true after assignment notification sent
    resolution: ""  # filled on close

**Never classify a gap as Overdue on an unverified rule.** The 🔴 Overdue classification means "we missed a binding deadline." If the rule's status is unverified (policy-diff set `status_verified: false`, or the rule is >12 months old / past its applicability date with no currency confirmation), the deadline may not be binding. Use 🟡 "Review needed" and note: "If this rule is in force as published, this would be overdue by [N] days. Verify rule status before escalating." Route unverified-rule items to `watch`, not to the active overdue/due-soon buckets; the `watch` revisit cadence forces a rule-status check before the item can re-surface as a compliance gap.

**`gap_type` semantics:**

| Value | Meaning | Typical reminder cadence | |---|---|---| | `none` | Policy already covers the requirement. Logged for audit trail only. Should be rare — if most entries are `none`, the diff is probably running against the wrong policy. | No auto-reminder. | | `partial` | Policy addresses the topic but doesn't fully cover the new requirement. Needs an amendment. | 30 days before due. | | `full` | Policy contradicts or silently omits the new requirement. Needs a rewrite or new section. | 30 days before due. | | `new-policy` | No existing policy covers this. Policy needs to be drafted. | 30 days before due. | | `watch` | Forward-looking item — ANPR, RFI, proposed rule not yet final. No compliance obligation today; policy work waits for the final rule. `due:` is a revisit date (typically the NPRM expected date or a one-year horizon), not a compliance deadline. | No auto-reminder; re-evaluate when an NPRM drops or at the revisit date. | | `comment-decision` | Pre-rulemaking comment decision pending — ANPR or NPRM where the team is deciding whether to file a comment. `due:` is the comment deadline. | 21 days before due (tighter than compliance gaps because comment-drafting windows are short). |

A `watch` or `comment-decision` entry is not a compliance gap — it's a tracking artifact for pre-rule items that the watch skill and comments skill produce. Surface them in the status report in their own bucket so counsel reading at 7am can tell at a glance which items are "fix this before a regulator notices" vs. "keep an eye on this."

Modes

Mode 1: Ingest from policy-diff

When policy-diff finds gaps, append them to gap-tracker.yaml. De-dupe — same requirement + same policy = same gap, don't double-count.

**After inge