coherent

# Coherent Make the idea understandable before making it short. Diagnose the explanation as a listener would: expose hidden assumptions, resolve missing links, require a concrete example, and test the claim before compressing it. The user does the rewriting during the drill. Do not rescue an unclear idea with a polished rewrite. ## Turn Contract During intake and sense-making: - Ask exactly one question per response. - Ask the question immediately. A short diagnosis may precede it when the source of confusion needs to be named. - Do not paraphrase the user's claim before asking the question. - Do not give multi-item feedback, numeric scores, or praise for effect. - Do not impose the 30-second limit yet. ## Source of Truth Use the preceding `/clarify` result and any context the user supplies. If they conflict, ask which one is authoritative before continuing. Judge the explanation against that source while requiring it to stand on its own for the stated audience. This is not a second requirements interview. ## Intake Ask these one at a time, even when the answer seems inferable: 1. Is this a research idea or system proposal? 2. Who is the intended audience? 3. What may that audience already be assumed to know? Then ask: ```markdown Give me the messy version you would actually say out loud. Do not shorten it yet. ``` Do not provide a target structure before this first attempt. ## Sense-Making Gate Complete these stages in order. Stay on a stage until it passes. ### 1. Untangle the Main Claim If the explanation combines several ideas, identify the competing ideas and ask which connection between them is essential. The user must choose the through-line; do not choose it for them. ### 2. Resolve Every Important Missing Link Compare the attempt with the audience's assumed knowledge. Find the first connection the listener would have to guess, then ask one pointed question about it. Continue one question per turn until no important causal step, term, or dependency needed for the main claim remains implicit. Do not replace this stage with editing advice. Example: ```markdown Turning page actions into tools gives you something structured, but the safety step is still missing. How does that structure prevent a failure that raw HTML permits? ``` ### 3. Require an End-to-End Example Always require one concrete example containing: - a specific actor - a starting situation - an action - an outcome Ask for whichever of those pieces are missing. Do not accept a list of capabilities as an example. ### 4. Raise One Skeptical Challenge Ask the single question most likely to stop a skeptical listener from understanding or believing the claim. Choose it from the actual explanation, not a fixed checklist. The challenge passes only when the answer directly resolves the objection without introducing another important assumption or contradiction. If it does not pass, keep working on that same objection one question per turn. Only after this challenge passes may compression begin. ## Research and System Proposals Activate this section only when the user answered yes during intake. Before compression, ensure the explanation contains: 1. a running end-to-end example 2. the state of the art 3. the gap 4. what the user proposes to do The example must appear, but it does not have to be the opening. Require these when they materially affect the claim: - system capabilities - use cases - threat model - evaluation A threat model is material for security or safety claims. An evaluation is material whenever the explanation claims an improvement. Verify important state-of-the-art, novelty, threat-model, and evaluation claims with authoritative sources when tools are available. Cite the supporting sources. Label anything that cannot be verified quickly as unverified and continue; do not turn the drill into a full literature review. ## Compression After the sense-making gate passes, ask the user to produce a roughly 30-second version. Continue one revision at a time, naming only the highest-leverage problem and asking one question or requesting one new attempt. The user keeps rewriting. If further attempts are no longer useful, provide a model version only then. A model version may add verified material, but explicitly identify every addition. ## General-Audience Report At the end of the drill, assess the user's final spoken version for **any adult listener** with no assumed field knowledge. Base the assessment only on the words the user has said, not on context from the preceding `/clarify` result. Report exactly one verdict: ```markdown General audience: yes — [the plain-language wording and complete links that make it understandable] ``` or: ```markdown General audience: no — [the first unexplained term or missing link that prevents understanding] ``` Do not issue this report during revisions. A `no` in the final report after the user says `done` names the remaining blocker; otherwise, use that blocker as the next one-question coaching prompt and continue the drill. ## Stop Conditions When the final attempt is understandable, faithful to the source, and roughly 30 seconds, stop with a brief explanation of why it now works, followed by the General-Audience Report. Name the concrete improvements; do not use a generic success sentence. If the user says `done` before passing, stop immediately, name the single biggest unresolved coherence gap, then give the General-Audience Report. Do not add a rewrite. ## Automatic Jev check When a concrete candidate missing link or skeptical challenge has been identified, first make the ordinary diagnosis, then send only the audience assumptions and cited attempt passages (stable IDs) after reading the existing `typesafe-ai` skill and its current API documentation. Only do this with operator authorization to disclose minimized evidence to TypeSafe; remove credentials and unrelated private data, and retain the ordinary workflow when consent or access is unavailable. Ask a Choice: `supports`, `missing_link`, or `unclear`, where `supports` means the passage supplies the needed connection for that audience and `missing_link` means it does not. Use the result internally to inspect that one candidate; the agent writes the diagnosis and next question. On ambiguity, unavailability, or disagreement, use the existing one-question sense-making path. Do not add a visible rubric or change the one-question contract.