docs(#401): universal teachback ritual + hard-rule tone (salvage from #477)#490
Open
michael-wojcik wants to merge 2 commits into
Open
docs(#401): universal teachback ritual + hard-rule tone (salvage from #477)#490michael-wojcik wants to merge 2 commits into
michael-wojcik wants to merge 2 commits into
Conversation
…nt at every dispatch
Add explicit "every dispatch, regardless of variety" imperative to the three
protocol documents that describe the teachback ritual, closing the gap where
the structured teachback_submit/teachback_approved form was canonical at
variety >= 7 but implicit below.
- pact-plugin/skills/pact-agent-teams/SKILL.md: teammate-side imperative
adjacent to the existing teachback section — teammate produces the
structured teachback_submit metadata via TaskUpdate at every dispatch.
SendMessage remains the notification channel; the structured metadata
carries the substance.
- pact-plugin/skills/orchestration/SKILL.md: lead-side mirror imperative in
the "Validating Incoming Teachbacks" section — lead produces the structured
teachback_approved metadata at every dispatch. Writing the structured form
IS the genuine engagement; its substring-inequality, citation-shape, and
grounding-reference requirements force actual reading instead of
rubber-stamp approval.
- pact-plugin/protocols/pact-ct-teachback.md: new top-level "Design
principle: shared understanding is constructed, not transmitted" section
placed before the existing Conversation-Theory / state-machine sections.
Design rationale:
(a) Pask's Conversation Theory framing — shared understanding between two
agents is CONSTRUCTED through mutual generative exchange, not
transmitted. Both sides must generate content grounded in the other's
text; the ritual implements that construction at every dispatch.
(b) User directive — "I think the instructions should be universally
applied to both teammates and the lead. Structured teachbacks at every
turn regardless of variety." The protocol applies uniformly; mechanical
enforcement is the variety-gated safeguard, not the scope definer.
(c) Q2 tightening plan resolution — the variety-7 gate threshold controls
mechanical enforcement (teachback_gate.py firing on missing or invalid
content). It does NOT gate whether the content should be produced.
Below the threshold, the discipline-based layer constructs shared
understanding with the same generative shape, just without mechanical
fallback.
Docs-only change. No source code modifications, no test additions, no
behavioral changes to the gate implementation. Pytest: 7292 passed,
3 skipped (no regression from baseline).
…ory tone
Cycle-9 introduced the "every dispatch, regardless of variety" scope but
framed it as "canonical practice" and exposed the variety-7 threshold and
mechanical-enforcement two-layer structure inside the instructional voice.
User correction: agent-facing instructional content uses MUST / no-exceptions
imperative; the mechanical enforcement layer (hooks, variety thresholds,
conditional behavior) is hidden from the instructional voice. From the
LLM's perspective reading the instruction, the practice is ALWAYS mandatory.
The fact that an additional mechanical safeguard fires at variety >= 7 is a
backend implementation detail that does not appear in the voice of the
instruction.
User's exact words: "from the LLM's perspective it should be mandatory every
turn. We are just hiding an additional layer of mechanical enforcement
behind the scenes, when the variety score warrants it."
Per-file treatment:
- pact-plugin/skills/pact-agent-teams/SKILL.md: rewrite the "Structured
teachback_submit at every dispatch" first paragraph to MUST imperative
("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, first_action.
All 4 sub-fields are required on every dispatch. A teachback without
these fields is not a teachback."). Strip the "below the threshold /
mechanical enforcement adds a second layer" sentence entirely. Preserve
the SendMessage + TaskUpdate co-produced trailing paragraph.
- pact-plugin/skills/orchestration/SKILL.md: rewrite the "Structured
teachback_approved at every dispatch" lead-side paragraph to MUST
imperative ("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, conditions_met. All 5
sub-fields are required on every approval."). Strip the variety-7
threshold sentence. Preserve the "bare-text teachback -> ask teammate to
re-submit via TaskUpdate" loophole-close at the end.
- pact-plugin/protocols/pact-ct-teachback.md: preserve the "## Design
principle: shared understanding is constructed, not transmitted" body
paragraphs as design-rationale (the mechanism-discussion legitimately
belongs here for mechanism auditors). Rewrite ONLY the trailing
Implication paragraph to hard-rule form ("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.").
Grep post-conditions (all verified zero-hits against softening/mechanism
chatter in the two SKILL files):
- grep "canonical practice" across pact-plugin -> 0 hits
- grep "below the threshold|at or above the threshold|mechanical enforcement
adds a second layer|variety-7|variety 7" in pact-agent-teams/SKILL.md -> 0 hits
- grep "below the threshold|at or above the threshold|mechanical enforcement
adds a second layer|variety-7|variety 7" in orchestration/SKILL.md -> 0
hits (the pre-existing "variety 7+" mention at line 140 is in the
Workflow Selection section and predates this work)
- grep "on every dispatch, no exceptions" across pact-plugin -> 2 hits
(one each in pact-agent-teams/SKILL.md and orchestration/SKILL.md)
Docs-only change. No source code modifications, no test additions, no
behavioral changes to the gate implementation. Pytest: 7292 passed,
3 skipped (unchanged from cycle-9 baseline).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Salvages cycles 9 + 9b from PR #477 (parked pending redesign per issue #489).
This PR ships the content + tone of the teachback protocol — what structured fields go in
teachback_submit/teachback_approved, and that the ritual applies universally at every dispatch. It does NOT ship the cooperative-halt blocking mechanism from cycle-10, which the dogfooding session revealed to be livelock-prone.Changes
pact-plugin/skills/pact-agent-teams/SKILL.md— teammate-side: every teachback MUST include structuredteachback_submitmetadata viaTaskUpdatewith 4 sub-fields (understanding,most_likely_wrong,least_confident_item,first_action). On every dispatch, no exceptions. A teachback without these fields is not a teachback.pact-plugin/skills/orchestration/SKILL.md— lead-side mirror: every teachback approval MUST include structuredteachback_approvedmetadata with 5 sub-fields (scanned_candidate,response_to_assumption,response_to_least_confident,first_action_check,conditions_met). An approval without these fields is not an approval.pact-plugin/protocols/pact-ct-teachback.md— new "Design principle: shared understanding is constructed, not transmitted" section with Pask's Conversation Theory framing. The ritual applies at every dispatch regardless of variety; mechanical enforcement (variety-7 threshold) is a hidden layer invisible in agent instructional voice.What this PR does NOT ship
What this PR DOES ship
Pure documentation / instructional voice changes codifying the content and universality of the ritual. The HOW (wait mechanism) is explicitly left open.
Commits
8e00f11docs(Codify variety-tiered blocking teachback using variety_scorer.py as backbone #401): cycle-9 universal teachback imperative — generative content at every dispatch1247b0cdocs(Codify variety-tiered blocking teachback using variety_scorer.py as backbone #401): cycle-9b sharpen teachback imperative to hard-rule mandatory toneBoth cherry-picked cleanly from PR #477 (teachback-gate-401 branch) onto a fresh branch off main.
Test plan
pytest pact-plugin/tests/from worktree root: 6411 pass, 3 skip (baseline — no new tests, no test changes)Related