Configures Claude Code hooks and Codex hooks.json/notify. Use when adding PreToolUse guards, Stop hooks, managed hooks, format-on-save, preflight, audits, or worktree/budget hooks.
日本語の概要は準備中です。原文の説明を表示しています。
Grounding-theory primitives for common ground and repair. Use when deciding whether to ask a clarifying question, confirming a handoff was understood, or fixing multi-turn drift.
インストールする前に、エージェントに与えられる指示の中身を確認できます。
Scope note — two senses of "grounding": This skill covers the Clark conversational sense: establishing shared meaning between parties (common ground, acceptance evidence, repair). It does not cover the LLM-attribution / RAG sense: whether a generated response is grounded in retrieved documents (citation faithfulness, hallucination detection). For the attribution sense, see ai-rag and the FACTS Grounding / RAGAS / Wallat et al. frameworks (sources FACTSGrounding2025, RAGAS2024, WallatFaithfulness2024 in data/sources.json).
Use the ten primitives below to establish enough shared understanding for the task. Delivered context, an acknowledgment, and demonstrated understanding are different evidence; none grants authority.
Static vs. dynamic grounding. Interpreting an opening brief is different from maintaining a joint plan across turns. Yao, Zou, and Hawkins (2026, preprint) observe dyads missing optimal allocations despite solving the negotiation task individually. Their observed failures motivate preserving settled state, identifying referents explicitly, and distinguishing exploratory proposals from commitments. These are application conventions, not a guarantee that an agent understood.
Laban et al. (2025) measure multi-turn degradation: LLMs lose an average of 39% across six generation tasks in underspecified multi-turn settings, and once a model takes a wrong turn it "gets lost" and does not recover — a reliability failure, not mainly a capability one. Operational inference: in multi-turn underspecified work, periodically consolidate accumulated requirements into one restated spec (#1, #3) rather than patching state in place; after a detected wrong turn, restart execution from the consolidated spec instead of continuing to build on the compromised thread.
Apply grounding-theory when:
Skip and use simpler alternatives when:
| # | Primitive | When to Reach For It |
|---|---|---|
| 1 | Common Ground | Audit what each party already shares before drafting any handoff |
| 2 | Grounding Criterion | "Grounded enough for what?" — set the bar before designing the protocol |
| 3 | Contributions: Presentation + Acceptance | Decompose a message into the two-step joint act it actually is |
| 4 | Evidence of Understanding | Design the explicit/implicit signals that close the loop |
| 5 | Repair | Plan how misunderstandings get caught and fixed |
| 6 | Presupposition | Audit what the message assumes its audience already knows |
| 7 | Audience Design | Match the brief to who will read it (not who wrote it) |
| 8 | Joint Commitment | Treat communication as joint action, not unilateral signal |
| 9 | Least Collaborative Effort | Optimize total effort across both parties, not just speaker effort |
| 10 | Grounding Cost / Tracks | Price the meta-channel — confirmations and repairs cost too |
Failure modes, checks, and supporting evidence: references/primitives-overview.md.
| # | Primitive | Failure Mode It Addresses |
|---|---|---|
| 1 | Common Ground | Treating "in the system prompt" as "shared with the agent" — common ground is what's believed mutual, not just present |
| 2 | Grounding Criterion | Over-grounding (excess confirmation overhead) or under-grounding (acting on uncertain interpretation) |
| 3 | Contributions: Presentation + Acceptance | "I sent the message, so we're done" — communication isn't complete until acceptance is signaled |
| 4 | Evidence of Understanding | Acknowledgment mistaken for task-specific understanding |
| 5 | Repair | Correction acknowledged while pre-repair assumptions still drive actions |
| 6 | Presupposition | Brief assumes context the recipient doesn't have (the skill's own inference: ambiguous-brief failures map here; MAST files specification issues under system design) |
| 7 | Audience Design | Brief depends on the writer’s private vocabulary or context |
| 8 | Joint Commitment | Sending a handoff mistaken for joint coordination |
| 9 | Least Collaborative Effort | Sender saves tokens while shifting larger interpretation and repair costs to recipients |
| 10 | Grounding Cost / Tracks | Confirmation/repair overhead ignored when budgeting communication |
Read references/formal-theory-map.md when source-level justification or production boundaries matter. Empirical evidence and its scope live in data/sources.json and references/primitives-overview.md.
The classical layer is stable; check publication status of newer preprints before citing them. Benchmark rates are specific to their datasets and models and require local measurement before becoming policy.
| Anti-Pattern | Grounding Theory Diagnosis | Fix |
|---|---|---|
| "I put it in the system prompt, so the agent knows" | Common ground (#1) confused with content delivery; presence ≠ mutual belief | Verify common ground via grounded probe (use a proportionate probe or inspectable first artifact). Track corrections as a candidate misalignment signal; test its relation to failures in your own traces |
| Subagent acts on an ambiguous or high-cost brief without exposing its interpretation | Grounding criterion (#2) is below the task risk | For reversible work, expose the working interpretation while proceeding; require an explicit restatement/response only when ambiguity can change an irreversible or costly action |
| User says "ok" / agent emits "ack" — taken as confirmation of understanding | Evidence of understanding (#4) confuses acknowledgment with comprehension | Use task-specific paraphrase, plan, or worked example when the criterion requires stronger evidence |
| No mechanism for "wait, I don't understand" once a task starts | Repair (#5) channel missing; errors compound | Provide explicit "ask for clarification" tool; reward its use when uncertainty is high. For consequential actions, compare the inferred task with user intent before execution (InferAct pattern); preserve existing authority |
| Repair happens, but the agent proceeds on its pre-repair assumptions | Repair (#5) treated as an utterance rather than a common-ground update; the correction is acknowledged and then not propagated | After a correction, require restatement of the revised shared state, not of the correction. Test locally whether corrections propagate (Poelitz et al., 2026, preprint, benchmarks common ground in human-AI collaboration) |
| A correction is silently adopted even when it conflicts with verified artifact state or a source | Repair (#5) conflated with sycophancy — a correction is evidence, not truth, and propagating it faithfully is not the same as propagating it correctly | Before restating the revised shared state, check a conflicting correction against verified state; if it conflicts, surface the conflict rather than silently adopting it. See ai-evals's sycophancy gate (references/conversational-feedback-signals.md) for the accuracy-anchored check this composes with |
| Brief mentions "the dashboard" without antecedent | Presupposition (#6) failed; agent fills in wrong referent | Audit briefs for definite references; resolve antecedents before handoff |
| Brief written in domain shorthand the recipient doesn't share; LLMs repeat similar follow-ups rather than pivoting to audience-state-informed questions | Audience design (#7) failed; speaker-centric, listener state untracked | Rewrite for the recipient's vocabulary; check by having a peer (or different agent) read it cold |
| Handoff treated as fire-and-forget | Joint commitment (#8) violated; communication framed as transmission | Use proportionate acceptance evidence; block only for unresolved consequential ambiguity or missing authority |
| Speaker minimizes own tokens, recipient must guess | Least collaborative effort (#9) optimized one-sidedly | Optimize total effort: a longer brief that prevents one repair round is cheaper than the round trip |
| Confirmation steps stripped to save tokens | Grounding cost (#10) underestimated; expected savings exceeded by failure cost | Compute expected total cost including failure-and-repair tail |
Context: Orchestrator dispatches a subagent on a non-trivial task. Inference, not a MAST claim: prompt, role, context, and stopping-condition ambiguity all appear before or during execution, so the brief is a primary failure surface.
agents-subagents/references/clarification-questions-protocol.md (bundle load-bearing questions and include a safe assumed default where possible).Protocol lookup at integration time. Read the deployed A2A specification for interrupted task states and the negotiated MCP elicitation specification for modes, allowed data, and response semantics. Do not assume a response meaning from another protocol revision: URL-mode acceptance does not establish completion of the out-of-band interaction. These mechanisms support turn-taking and authority checks; they do not prove shared interpretation.
For clear, authorized reversible work, expose the working interpretation or first artifact and continue. Wait only when unresolved ambiguity or missing authority can change a consequential action.
Worked example. For a reversible draft, the subagent replies, "Working interpretation: refactor the OAuth2 handler under src/auth/ while preserving endpoints," and begins with an inspectable first diff. The orchestrator can interrupt if that interpretation is wrong. If the same ambiguity controls a production auth migration or credential change, the subagent stops after the restatement and waits because the repair cost and authorization boundary justify blocking acceptance.
Context: An agent loops for many turns; context gets compressed by the harness; common ground decays.
Context: Two agents must converge on a joint plan over several turns — negotiation, resource allocation, division of labor, peer review. Distinct from a one-shot handoff: the failure is not a bad brief but a failure to maintain and revise shared state across turns. Individually capable agents still fail as dyads here (Yao et al. 2026).
For end-of-run reports, use the agent-to-user handoff pattern rather than duplicating the recipe here.
Rifts (ACL 2025) observed lower clarification and follow-up rates for LLMs in its sampled conversations; measure missed and unnecessary asks in your app rather than treating those rates as a baseline. Set the grounding criterion (#2) per intent: verify target and authority before booking, purchase or deletion; an inspectable result suffices for a reversible lookup or draft. Track turns where the user corrects or restates, and test whether they predict failures; a correction count alone does not establish cause or fault.
Test shared-meaning failures alongside technical root causes when the output diverges from the agreed task.
| Signature | Distinguishing test | Fix |
|---|---|---|
| Silent misalignment: parties proceed many turns before anyone notices they meant different things; no error is raised, only a late, expensive divergence | Ask each party independently to state the current shared goal in one sentence. If they diverge and neither noticed, this is it | Scheduled, low-cost restatement checkpoints; there will be no symptom until the cost is sunk (#1, #2) |
| Costly-repair spiral: a misunderstanding is "fixed" but the fix was not grounded either, so repair rounds compound | Track repair-round cost (tokens, time, trust) over the incident. If it is rising, the repair channel lacks an acceptance phase | Ground the repair like the original contribution: expose the revised shared state before the next affected action; require a response only if consequential action still depends on unresolved ambiguity or missing authority (#3, #5, #9) |
Explicit protocols (restate-and-confirm, structured acceptance, mandatory paraphrase) cost tokens, time, and social friction on every interaction. Implicit grounding (proceed on inferred understanding, correct if wrong) costs nothing until it's wrong, then costs a lot. The judgment call is not "always verify" or "never verify" — it's pricing the crossover for a given interaction class, set deliberately once rather than improvised per instance.
Reach for explicit verification when: the action is irreversible or expensive to undo (deploys, sends, payments, deletes); personal common ground is low (new user, new subagent, session start, just after context compression); the medium has expensive repair (async, high-latency, no real-time interrupt — batch jobs, cross-team handoffs, long agent loops); or errors are silent by default — the system won't surface a wrong interpretation on its own, it will just produce plausible-looking wrong output.
Stay with implicit grounding when: the action is cheap to reverse and errors surface immediately (exploratory reads, drafts, low-stakes lookups); personal common ground is already rich (many prior turns validated the shared model); the medium has cheap repair (synchronous chat, pair programming, a fast interrupt path); or over-verifying has a real cost of its own — added friction lowers the rate at which people or agents initiate contact at all, which can be a bigger loss than the occasional repair.
A signature or acknowledgment can close an approval gate while leaving interpretation untested. Choose evidence that detects the specific misunderstanding at issue.
Least collaborative effort (#9) is usually read as a dialogue-efficiency principle. Applied to agent design, it reframes a common local optimization as a false economy:
data/sources.jsonWhen prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
Configures Claude Code hooks and Codex hooks.json/notify. Use when adding PreToolUse guards, Stop hooks, managed hooks, format-on-save, preflight, audits, or worktree/budget hooks.
日本語の概要は準備中です。原文の説明を表示しています。
Configures and hardens Claude Code and Codex MCP servers. Use when connecting databases, APIs, SaaS, building servers, or serving a clearance-filtered knowledge base.
日本語の概要は準備中です。原文の説明を表示しています。
Owns instruction files: AGENTS.md, CLAUDE.md, personal and repo rules. Use when writing, pruning, auditing them, sharing rules across Claude and Codex, or fixing ignored rules.
日本語の概要は準備中です。原文の説明を表示しています。
Creates and audits agent skills: SKILL.md, references, scripts, runtime metadata. Use when writing, validating, or security-reviewing a skill, or fixing truncated skill listings.
日本語の概要は準備中です。原文の説明を表示しています。
Adds per-skill learnings loops for dated patterns, mistakes, and domain facts. Use when wiring skill memory, consolidation, or drift audits.
日本語の概要は準備中です。原文の説明を表示しています。
Chooses subagent, team, workflow, or debate and launches it on Claude Code or Codex. Use when delegating, running agent review boards, or installing shared agents.
日本語の概要は準備中です。原文の説明を表示しています。