comprehension-sync

---
name: comprehension-sync
description: Keep a human and coding agent mutually aligned while they make a meaningful software change. Use for thin-slice collaboration, shared-understanding check-ins, human approval of consequential decisions, and mental-model handoffs—especially when the user wants to avoid black-box implementation or comprehension drift. Do not use for fully delegated trivial edits, ordinary status reporting, or post-hoc codebase tutorials.
metadata:
  version: "0.1.0"
license: MIT
---

# Comprehension Sync

Maintain enough shared understanding for the human to direct the work and own the result without requiring them to inspect every agent action or prescribe every implementation detail.

Treat alignment as bidirectional:

- human to agent: outcome, context, what must remain true, acceptable trade-offs, and decision authority;
- agent to human: verified system model, intended change, consequential discoveries, implementation result, and remaining uncertainty.

The goal is compatible mental models, not identical information. Keep the interaction proportional to the change.

## Work from observable evidence

Obey repository instructions. Inspect the relevant source, tests, diff, public contracts, and runtime behavior before making implementation claims. Prefer normal code navigation and clickable source or diff links so the human can inspect evidence directly.

Label important claims when their status is not obvious:

- **Verified** — supported by source, tests, configuration, or observed behavior.
- **Inferred** — the best current interpretation, but not explicitly established.
- **Unknown** — consequential information not yet available.

Never request, expose, or depend on private chain-of-thought. Concise rationale and observable failed attempts are valid evidence; hidden reasoning is not.

## Establish the alignment snapshot

Before a meaningful repository mutation, establish only the information needed to choose the first slice:

1. **Outcome** — what should become observably true for the user or system.
2. **Current model** — the smallest verified explanation of how the affected behavior works now.
3. **Must remain true** — business rules, compatibility promises, safety properties, and technical invariants that the change must preserve.
4. **Decision boundary** — decisions the agent may make locally and decisions the human retains.
5. **First slice** — the smallest end-to-end change that produces evidence and teaches something useful.
6. **Unknowns** — only uncertainties that could change that slice.

Present this as a short alignment snapshot, not a project plan. If the request already establishes these facts, reflect them briefly and proceed instead of asking the user to repeat or reapprove them. If a missing fact would materially alter the outcome, scope, or architecture, explain the gap and wait for alignment.

## Work in thin slices

A useful slice changes one coherent behavior, has an observable verification path, and leaves a reviewable mental-model delta. It may span several files when that is the smallest end-to-end boundary; do not reduce a slice to arbitrary file-by-file edits.

For each slice:

1. state what will become true and what remains outside the slice;
2. implement within the agreed decision boundary;
3. verify the behavior in proportion to risk;
4. provide the mental-model handoff;
5. let the human continue, redirect, inspect more evidence, or stop.

Do not turn “continue” into approval for a larger unreviewed phase. It authorizes the next described slice unless the human explicitly delegates broader scope.

## Pause at consequential decisions

Pause when a discovered decision would materially change any of these:

- user-visible behavior or the meaning of the requirement;
- public APIs, persisted data, schemas, migrations, or compatibility;
- ownership of business rules, state, concurrency, transactions, or failure recovery;
- security, privacy, permissions, destructive effects, or reversibility;
- production dependencies, external services, deployment shape, or operating cost;
- major module boundaries or abstractions that constrain future changes;
- the agreed slice, complexity budget, or a previously stated must-remain-true condition.

Do not pause for local naming, small refactors, test organization, or other reversible implementation choices inside the agreed boundary.

Before asking the human to choose, read and follow [references/decision-brief.md](references/decision-brief.md). If evidence invalidates the shared outcome or current model, stop and realign rather than presenting a cosmetic choice.

## Hand off a mental model, not a progress summary

After each completed slice, read and follow [references/mental-model-handoff.md](references/mental-model-handoff.md). The handoff must help the human reason about the resulting system. Show the relevant source or diff anchors; do not substitute a narrative for access to the implementation.

Treat the handoff as a semantic completion gate. It is not complete unless the human can answer, from the handoff:

- which components now participate and what each one owns;
- how one representative input or event travels through them;
- where the consequential branch, state change, or failure is decided;
- how the implementation preserves the aligned constraints;
- where to enter the source to verify or continue the work.

A feature list, changed-file list, test report, or chronological account of agent actions does not satisfy this gate, even when placed under the required headings. Explain the implementation at the level of control flow, data flow, state ownership, and key contracts appropriate to the slice. Do not expose private chain-of-thought; describe verifiable design rationale and source behavior.

Before closing the slice, perform the closure protocol in the handoff reference against the final source and diff. Draft the resulting-system model and representative execution path before writing the ordinary completion summary. If those two parts are missing, generic, or could have been written before the implementation existed, do not claim the slice is complete. Rewrite the handoff from the implementation evidence first; place changed files, checks, and commit information afterward as supporting evidence.

Keep the handoff compact enough to review before more work begins. Expand a path or component on request instead of front-loading an exhaustive explanation.

## Keep artifacts lightweight

Use the conversation as the default alignment surface. Create durable briefs, ADRs, diagrams, or handoff files only when the user asks, repository conventions require them, or the decision must survive beyond the current task. Do not create a research harness, reviewer packet, scoring gate, or comprehension quiz unless explicitly requested.

If the human reports confusion, friction, or loss of context, treat that as an alignment failure. Stop advancing the implementation, restore direct access to the relevant code and diff, rebuild the smallest useful model, and let the human decide where to resume.