ambiguity-gate

Files (12)

• SKILL.md
• 01-fire-a5-unbounded-reset.md · tests/
• 02-fire-a6-vague-verb.md · tests/
• 03-fire-a1-target-survives-reading.md · tests/
• 04-fire-a2-a3-cut-point.md · tests/
• 05-fire-a7-constraint-conflict.md · tests/
• 06-nofire-brake-resolves.md · tests/
• 07-nofire-gate-a-status-query.md · tests/
• 08-nofire-write-two-fails.md · tests/
• 09-nofire-mode-directive-and-ack.md · tests/
• 10-nofire-operational-condition.md · tests/
• README.md · tests/

SKILL.md (first lines)

# Ambiguity Gate

**A task-shaped request with residual ambiguity does not get acted on until the interpretation is chosen.**

The branch variable is not your role. It is **whether a human is watching the surface on which the
question would appear.** Plan mode is a blocking modal: on a watched surface it is the cheapest
possible gate; on an unwatched one it is indistinguishable from a hung session — and it eats the
injects sent to wake it. Role is the observable proxy for "watched", nothing more.

Normative source: `docs/rules.md` **Rule 37** (HARD). This skill is its operational aid, not its
authority — the rule binds even where this skill is not installed.

## Where this skill fits

| Situation | Route to | Boundary |
|---|---|---|
| The request has ≥2 plausible readings — we do not know **what the user wants** | **`ambiguity-gate`** (this skill) | Request-space multiplicity. **Only the user can resolve it.** |
| The goal is known; **2+ equally valid approaches** to reach it | `auto-multi-llm-review` | Solution-space multiplicity. An LLM panel *can* resolve it. **If both fire, ambiguity-gate goes first** — you cannot deliberate approaches to an unknown target. Deliberation may then run inside the plan or after approval. |
| An artifact already exists (design doc, review feedback, dead-ended debug) and needs multi-AI verification | `deliberation-gate` | Fires on **outputs**; this gate fires on **inputs**. Sequential, never competing. |
| A plan exists and must be stress-tested into a written ADR (Rule 24 SPEC FIRST) | `grill-with-adr` | **Downstream exit**, not a competitor: gate → approved plan → if the decision is ADR-weight (scope ≥ cross-project, or one-way) → grill. Also: grill is user-invoked; this gate is automatic. |
| oh-my-claudecode "Broad Request Detection" → `explore` → `architect` → `plan` | Compatible — runs **inside** plan mode | OMC owns an optional *interview method*; Rule 37 owns the *gate* (no action before approval). Art.17.2: OMC must never be required — the gate uses native plan mode and works with OMC absent. Conflict exists **only** if an OMC flow acts before approval; then Rule 37 wins. |
| Design exploration before building something new | `superpowers:brainstorming` | Brainstorming explores a *chosen* direction; the gate decides *which* direction is being asked for. Brainstorm inside plan mode, or after approval. |
| "Why does this break?" rather than "what should we build?" | `diagnose` | Wrong axis entirely — no ambiguity gate on a reproduction. |

---

## Step 1 — Gate A: is this task-shaped?

The request asks for a change to durable state (files, config, running systems, dispatched work)
or for a deliverable artifact (doc, design, report). Excluded, enumerated:

| Excluded class | Example |
|---|---|
| Answerable from context already loaded | "what did #743 conclude?" |
| Status / read-only query | "which sessions are alive?" |
| 1-line ack, follow-up, `send-key`, broadcast | "ok", "go", "yes do that" |
| Preference / tone / mode directive | "caveman mode", "shorter answers" |
| Conversation about a decision already made | "why did we pick two-way?" |

Enumerating exclusions is deliberate: a positive definition of "task" drifts between readers, a
closed exclusion list does not. **Gate A fails ⇒ stop here. No gate, answer normally.**

Operational conditions are not requests. A sandbox prompt, a trust modal, a blank panel, a stuck
session, stale cleanup, AUTO_REPORT — Rule 30 autonomy is untouched by this gate.

> **If skipped:** the gate fires on chatter and status queries. Every "ok" becomes an approval round
> trip, the user learns to route around it, and the gate stops carrying information — worse than no
> gate, because it still *looks* like one.

## Step 2 — Resolve by reading first (the brake)

Cheap disambiguation comes **first**. Only **residual ambiguity that survives reading** triggers
the gate.

The stopping condition is a criterion, not a budget — an effort count is not a test two readers can
apply:

> **Does the residual difference between the readings concern the user's *intent*, or the
> repository's *facts*?** Facts are readable — keep reading. **Intent is not in the repo** — no
> amount of further reading will settle it, and that is exactly when the gate fires.

A targeted search (grep the named symbol, read the named file, `tq-status`) settles fact-shaped
differences; roughly three such calls is the practical point past which a fact-shaped difference
would already have resolved. That figure is **guidance for the judgment, not the threshold** — the
decidable test is the intent-vs-facts distinction above, and a reader who reaches a different call
count but the same intent-vs-facts verdict has applied the rule correctly.

This is the single most important step in the skill.

> **If skipped:** "무조건" degenerates into an interview before every task. Users approve without
> reading within days, and the gate becomes a tax that buys nothing. Over-triggering — not
> under-triggering — is the way this gate fails.

## Step 3 — Gate B: does a signal survive the reading?

Fires if **≥1** signal holds:

| # | Signal | Firing test |
|---|---|---|
| **A1** | **Target** | ≥2 concrete referents in the repo match the named target and the request does not disambiguate |
| **A2** | **Scope** | The change boundary has ≥2 defensible cut points (this call site / this module / every caller) |
| **A3** | **Deliverable** | You cannot name the exact file(s) or artifact(s) that will exist when it is done |
| **A4** | **Success criteria** | You cannot state one checkable pass/fail condition |
| **A5** | **Destructive op: unbounded *or* irreversible** | delete / overwrite / force-push / reset / drop / publish / kill that **either** (i) lacks an explicit bound (which files, which remote, which sessions), **or** (ii) **irreversibly destroys work not recoverable from any remote or backup**, absent an explicit user acknowledgement of that loss. **Fires alone, always** |
| **A6** | **Vague verb, no target** | improve / enhance / fix / refactor / 정리 / 개선 with no named file, function, or symbol |
| **A7** | **Constraint conflict** | Proceeding requires choosing which standing rule, ADR, or constitutional article to violate |

A6 is the oh-my-claudecode "Broad Request Detection" heuristic, cited rather than reinvented
(Art.1 경량; the heuristic is sound, only its plugin coupling is unacceptable).

**The write-two rule.** A signal fires **only if you can write down the ≥2 competing readings
verbatim.** Suspicion is not a signal. If you can produce two, you may not silently pick one
(응답원칙 §4); if you cannot produce two, the signal did not fire and you proceed.

The written interpretations *are* the first section of the plan — detecting the ambiguity and
drafting the plan are the same act. No extra work, and the plan cannot be vaguer than the detection.

> **If skipped:** two readers of the same request disagree on whether it fired, and the rule stops
> being enforceable. Writing the two readings is the entire mechanism for inter-reader agreement.

**Decision rule:** `Gate A pass AND (≥1 of A1–A7 survives reading) → ambiguous`.

## Step 4 — Branch by watched surface

| Branch | Condition | Action |
|---|---|---|
| **Interactive** | human watching this surface | `EnterPlanMode` → plan whose §1 is the written interpretations + recommendation → wait for approval → `ExitPlanMode` → act |
| **Dispatched worker** | nobody watching | **MUST NOT enter plan mode.** `telepty inject` **HOLD** to orchestrator with the same written interpretations + recommendation → wait. Orchestrator opens a HITL Gate (`bin/hitl.sh open --kind decision --resume reinject`) → `awaiting_user` → resume by re-inject |

**Detection signal — one env var:**

```sh
[ "${AIGENTRY_WORKER_SESSION:-}" = "1" ] && echo worker || echo interactive
```

Set to `1` by `bin/dispatch.sh` in the generated per-session `worker-launcher.sh`, for **all** CLIs
(claude / codex / gemini), and already load-bearing as the orchestrator-vs-worker discriminator in
`bin/session-cleanup.sh`. Do not infer the branch from cwd, from the `[SAWP]` envelope, or from
`TELEPTY_SESSION_ID` — the first is empirically wrong under cwd decoupling, the second is invisible

From dmsdc-ai/aigentry-devkit, MIT.

More from dmsdc-ai/aigentry-devkit