synaptic-labs-ai/pact-plugin/pact-teachback

Teachback — Store Now

Canonical schema at a glance

The full teachback payload — all required fields plus the optional method-reconstruction sub-object — at the correct nesting level. Skim this first if you only have time for one section; the rest of the skill explains the why and the surrounding choreography.

TaskUpdate(taskId, metadata={
 
    # Top-level metadata key #1: teachback_submit
    # 5 canonical fields. variety_acknowledgment is an OBJECT (not a string).
    # reasoning_reconstruction is a sibling field of the other 4 (not nested
    # inside any of them, not placed on metadata.handoff).
    "teachback_submit": {
        "understanding":         "<...>",
        "most_likely_wrong":     "<...>",
        "least_confident_item":  "<...>",
        "first_action":          "<...>",
        "variety_acknowledgment": {
            "rationale_articulates_this_dispatch": "yes" | "no" | "concern",
            "concern": "<required when value != 'yes'>"
        },
        # Sibling field — optional below variety 11, required at 11+.
        # The 3 sub-keys are EXACTLY these three names, no substitutions.
        "reasoning_reconstruction": {
            "decision_attribution": "<...>",
            "assumption_trace":     "<...>",
            "contingency_clause":   "<...>"
        }
    },
 
    # Top-level metadata key #2: intentional_wait
    # SEPARATE top-level sibling of teachback_submit — NOT nested inside it.
    # Written via a SECOND TaskUpdate call after the notify SendMessage; see
    # Action: store teachback now below for the load-bearing 3-step ordering.
    "intentional_wait": {
        "reason":            "awaiting_lead_completion",
        "expected_resolver": "lead",
        "since":             "<canonical_since() output>",
        "covers_since":      "<the same value as since>"
    }
})

Each field's full purpose, the variety-band trigger for reasoning_reconstruction, and the 4 common wrong-shape mistakes appear in the sections below. The Common mistakes section enumerates the 4 wrong shapes the runtime advisory layer at hooks/task_lifecycle_gate.py catches at write time.

What a teachback is

Invoking this skill means you are about to submit a teachback for your current task. Do not proceed to implementation work until you have stored it AND received the team-lead's acceptance.

A teachback is a Pask Conversation Theory verification gate. Before you start implementing, you restate your understanding of the task so the team-lead can catch misunderstandings early, before you burn context on a wrong implementation.

Under the Task A + Task B dispatch shape, your teachback is the deliverable of Task A. Task B (the primary work) is blockedBy=[A]: it remains VISIBLE and readable in your TaskList (annotated as blocked) but is not claimable — the blockedBy edge filters it from the claimable set, it does not hide or lock it — until the team-lead accepts your teachback by transitioning Task A to completed, which makes Task B claimable.

The 5 canonical fields (Step 1) are the L1 (procedure-level) gate; the optional reasoning_reconstruction nested field enables the L1.5 (method-level) gate at high-variety dispatches — see pact-ct-teachback.md §When to Method-Reconstruct. Variety-band thresholds live at the SSOT in hooks/shared/variety_scorer.py (COMPACT_MAX / ORCHESTRATE_MAX / PLAN_MODE_MAX + route_workflow); do not hard-code the 6 / 10 / 14 thresholds.

Action: store teachback now

Ordering invariant (audit anchor): the three steps below MUST execute in the order Step 1 → Step 2 → Step 3 — metadata.teachback_submit write FIRST, then notify SendMessage, then intentional_wait SET. This ordering is load-bearing for the team-lead's Read-Trigger Precondition: the lead must wait for teammate's wake-signal SendMessage before treating the raw JSON read as authoritative, but the SendMessage is only safe to send AFTER the metadata write has landed on disk. Reversing Step 1 and Step 2 produces false-empty raw reads on the lead side that have triggered false-positive teachback rejection cycles. Reversing Step 2 and Step 3 (idle before SendMessage) silently strands the lead — they will never see the wake-signal because you went idle without sending it. Editors of this skill: do NOT re-order these steps. The write persists the durable copy; the notify carries it verbatim, so the lead's acceptance keys on the message and their raw read becomes the deferred audit.

Step 1 — write the teachback to task metadata (5 canonical fields + 1 optional nested field):

⚠️ Write the full sub-object in ONE call. TaskUpdate merges metadata at the TOP LEVEL only. A write that carries part of a nested sub-object REPLACES that sub-object. It erases each field you omit, and it reports no error. A write to one TOP-LEVEL key does not change a different TOP-LEVEL key, which is why Step 1 and Step 3 are different calls. If you must correct one field after the write, RE-SEND THE FULL OBJECT, and include each other field unchanged. Then read the task file back and enumerate the keys of metadata.teachback_submit.

TaskUpdate(taskId, metadata={"teachback_submit": {
    "understanding": "<what you understand you're building, key constraints, interfaces>",
    "most_likely_wrong": "<the part of your understanding you are least confident about>",
    "least_confident_item": "<one specific assumption you'd like the team-lead to confirm>",
    "first_action": "<the first concrete step you will take after teachback approval>",
    # ANTI-PATTERN: a free-text STRING here is rejected. variety_acknowledgment
    # MUST be an OBJECT with the 2 keys shown below. The runtime advisory
    # `variety_acknowledgment_schema_invalid_at_write_time` fires at TaskUpdate
    # if you submit a string. See pact-teachback skill Common mistakes row 1.
    "variety_acknowledgment": {                  # REQUIRED — see trigger paragraph below the JSON
        "rationale_articulates_this_dispatch": "yes" | "no" | "concern",
        "concern": "<required when value != 'yes'; names the smell>"
    },
 
    # ANTI-PATTERN: reasoning_reconstruction belongs HERE — a sibling field on
    # teachback_submit, NOT inside metadata.handoff. The handoff carries
    # reasoning_chain (the sender's own reasoning); the teachback carries
    # reasoning_reconstruction (your reconstruction of the upstream's
    # reasoning). Symmetric concept, different slot. The runtime advisory
    # `reasoning_reconstruction_in_handoff` fires if you place it on the
    # handoff. See pact-teachback skill Common mistakes row 2.
 
    # OPTIONAL: include per §When to Method-Reconstruct in pact-ct-teachback.md
    # (required at variety >= 11; recommended at 7-10; skipped at 4-6)
    # ANTI-PATTERN: the 3 sub-keys are EXACTLY these three names —
    # decision_attribution / assumption_trace / contingency_clause. Substituting
    # alternatives (e.g. "what-I-learned", "falsification-attempts",
    # "most-likely-wrong-prediction") is rejected as
    # reasoning_reconstruction_subkeys_invalid at write time and as
    # malformed_reasoning_reconstruction at lead-side completion-time review.
    # See pact-teachback skill Common mistakes row 3.
    "reasoning_reconstruction": {
        "decision_attribution": "I understand <upstream agent> chose <decision> because <their stated reason>",
        "assumption_trace":     "This reasoning depends on <assumption A>, <assumption B>, ...",
        "contingency_clause":   "If <assumption A or B> changes, the decision should change to <alternative>"
    }
}})

Read Task B's four variety SCORES (via Task A's blocks[0]) when needed; read the *_rationale strings ONLY AFTER composing the other four fields above. Required: a rationale read earlier cannot be un-read. — TaskGet is metadata-blind; read the task file (team name from pact-session-context.json, team_name field). SCORES: cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/tasks/{team_name}/{taskId}.json" | jq '.metadata.variety|map_values(select(type=="number"))'. RATIONALES, afterwards: the same cat piped to jq .metadata.variety. Judge each of the four per-dimension rationales against THIS dispatch's complexity and record yes / no / concern; when not yes, name the smell in concern. A rationale reading `WITHHELD: ignorance-dependent dispatch` is deliberate, not malformed — record `concern` QUOTING that literal verbatim; do NOT ask for a re-stamp. Full review workflow: `protocols/pact-variety.md` §Variety Calibration Record.

Step 2 — notify the team-lead (carrying the canonical payload verbatim):

SendMessage(
    to="team-lead",
    message=(
        "[<your-agent-name>→team-lead] Teachback submitted on Task #<A_id>. "
        "TEACHBACK-PAYLOAD-BEGIN "
        "understanding: <...> "
        "most_likely_wrong: <...> "
        "least_confident_item: <...> "
        "first_action: <...> "
        "variety_acknowledgment.rationale_articulates_this_dispatch: <yes|no|concern> "
        "variety_acknowledgment.concern: <... only when non-empty> "
        "reasoning_reconstruction.decision_attribution: <... when written> "
        "reasoning_reconstruction.assumption_trace: <... when written> "
        "reasoning_reconstruction.contingency_clause: <... when written> "
        "TEACHBACK-PAYLOAD-END "
        "The payload is a verbatim copy of metadata.teachback_submit; fields you did not write are omitted. "
        "Idling on awaiting_lead_completion. "
        "boundary-drain: [inbox empty | reconciled <n> directive(s) — <one-line summary>]"
    ),
    summary="Teachback submitted: <topic>"
)

One line, space-joined; the summary never carries payload content (it truncates at 200 chars). If team-lead is unreachable, send the notify to main.

After writing the payload, read the task JSON back and confirm every field is present, non-empty, and ends on its intended final content — a sender-side output cut lands mid-JSON and surfaces as a write error, not as silence. This check holds at any size.

# ANTI-PATTERN: Step 1 and Step 3 are SEPARATE TaskUpdate calls writing

SEPARATE top-level metadata keys. Nesting intentional_wait INSIDE

teachback_submit (one combined TaskUpdate) hides it from

missed_wake_scan.py, which reads metadata.intentional_wait and does

not descend into nested objects, so no missed-wake alarm is emitted.

is_self_complete_exempt governs self-completion exemption instead and

does not read the field in either placement. The runtime advisory

intentional_wait_nested_in_teachback_submit fires at write time. See

pact-teachback skill Common mistakes row 4.

Step 3 — SET `intentional_wait` and idle:

TaskUpdate(taskId, metadata={"intentional_wait": {
    "reason": "awaiting_lead_completion",
    "expected_resolver": "lead",
    "since": "<canonical_since() output: tz-aware ISO-8601 UTC>",
    "covers_since": "<the same value as since>"
}})

Do NOT begin Task B until Task A's status transitions to completed. The lead's acceptance SendMessage resumes you — you cannot self-wake to poll TaskList while idle. Then END THE TURN (idle).

On rejection (team-lead writes metadata.teachback_rejection and sends a wake-signal SendMessage carrying the rejection payload verbatim): see pact-agent-teams §On Rejection.

Common mistakes