diff --git a/pact-plugin/protocols/pact-ct-teachback.md b/pact-plugin/protocols/pact-ct-teachback.md index 813ccc03..3411e66e 100644 --- a/pact-plugin/protocols/pact-ct-teachback.md +++ b/pact-plugin/protocols/pact-ct-teachback.md @@ -1,3 +1,29 @@ +## Design principle: shared understanding is constructed, not transmitted + +Per Pask's Conversation Theory, shared understanding between two agents is +CONSTRUCTED through mutual generative exchange — not transmitted from one +to the other. The teachback protocol implements this construction: the +teammate produces self-identified risk plus concrete plan; the lead +produces independent-read verification plus distinct-risk scan. Both sides +generate content grounded in the other's text. + +The ritual applies at every dispatch, regardless of variety. Mechanical +enforcement (the variety-7 gate threshold in `teachback_gate.py`) is a +second-layer safeguard for high-consequence work — it does NOT define the +scope of the ritual itself. Below the threshold, the discipline-based +layer (orchestrator reading the teammate's teachback; teammate receiving +the orchestrator's structured approval) constructs shared understanding +with the same generative shape, just without mechanical fallback. + +**Implication**: `teachback_submit` and `teachback_approved` MUST be +produced at every dispatch in every PACT workflow. No exceptions. The +variety-7 threshold is a hidden mechanical enforcement layer — invisible +in agent instructional voice, and does not gate whether the structured +form is produced. From the agent's perspective, producing the structured +form is always mandatory. + +--- + ## Conversation Theory: Teachback Protocol > **Source**: Gordon Pask's Conversation Theory, applied to LLM multi-agent systems. diff --git a/pact-plugin/skills/orchestration/SKILL.md b/pact-plugin/skills/orchestration/SKILL.md index 6641f4e2..47ccf089 100644 --- a/pact-plugin/skills/orchestration/SKILL.md +++ b/pact-plugin/skills/orchestration/SKILL.md @@ -459,6 +459,19 @@ A list of things that include the following: When an agent sends a teachback, **compare it against the task as you dispatched it — check for both misstatements AND omissions of the objective, constraints, or success criteria**. If you spot a misunderstanding, reply with a correction via `SendMessage` before any other action — the agent is already working, so the correction window is short. Prevents **misunderstanding disguised as agreement** from going undetected until TEST phase. +**Structured `teachback_approved` at every dispatch.** Every teachback you +validate — on every dispatch, no exceptions — MUST include a +`teachback_approved` metadata write via `TaskUpdate` with the sub-fields +`scanned_candidate`, `response_to_assumption`, `response_to_least_confident`, +`first_action_check`, and `conditions_met`. All 5 sub-fields are required +on every approval. Writing the structured form is how you genuinely engage +with the teammate's teachback — the substring-inequality, citation-shape, +and grounding-reference requirements force actual reading rather than +rubber-stamp approval. An approval without these fields is not an approval. +If a teammate sent a bare-text teachback without the structured +`teachback_submit` metadata, reply via `SendMessage` asking them to +re-submit via `TaskUpdate` — the structured form is what you respond to. + #### Expected Agent HANDOFF Format Every agent delivers a structured HANDOFF stored in task metadata. Read via `TaskGet(taskId).metadata.handoff` when needed: diff --git a/pact-plugin/skills/pact-agent-teams/SKILL.md b/pact-plugin/skills/pact-agent-teams/SKILL.md index f5e9c87c..695497c7 100644 --- a/pact-plugin/skills/pact-agent-teams/SKILL.md +++ b/pact-plugin/skills/pact-agent-teams/SKILL.md @@ -63,6 +63,20 @@ content via `@`-ref. Background: [pact-ct-teachback.md](../../protocols/pact-ct-teachback.md) (optional — protocol rationale and design history). +### Structured `teachback_submit` at every dispatch + +Every teachback you produce — on every dispatch, no exceptions — MUST +include `teachback_submit` metadata via `TaskUpdate` with the sub-fields +`understanding`, `most_likely_wrong`, `least_confident_item`, and +`first_action`. All 4 sub-fields are required on every dispatch. A +teachback without these fields is not a teachback. + +The `SendMessage` notification described above remains the channel that +alerts the lead a teachback is ready to read. The structured +`teachback_submit` metadata is what the lead reads, validates, and replies +to. Produce both at every dispatch: `SendMessage` carries the notification; +`TaskUpdate(metadata={"teachback_submit": {...}})` carries the substance. + ## Progress Reporting Report progress naturally in your responses. For significant milestones, update your task metadata: