| name | clarity-find-gaps |
| description | Diagnose where explanations skip steps or use unexplained terminology. Use when: (1) asked to identify gaps or missing steps, (2) user asks for clarification, (3) explanation uses terms before defining them, (4) instructions followed without success, (5) asked to review explanation or documentation |
Find Gaps
Detect where explanations lose readers by temporarily setting aside expert knowledge to experience the text as the intended audience would.
Instructions
When reviewing explanations for gaps, I shift from the writer's perspective to the reader's vantage point, watching for places where understanding breaks down.
-
Establish the reader's starting point - Identify what knowledge the audience brings, what they're learning, and where I'm assuming things are obvious that aren't, since those assumptions mark where expert knowledge blinds writers to gaps.
-
Trace logical connections - Read sentence by sentence to verify each follows from what came before, checking whether conclusions are actually established or require missing inferential steps, especially where writers jump from problem to solution without showing the connecting reasoning.
-
Flag unexplained terminology - Mark every technical term or specialized concept at first use, verify its meaning is established before it's needed, and watch for circular definitions where new terms define other new terms, creating dependency loops readers can't bootstrap from.
-
Identify missing context - Look for statements that assume background knowledge the audience lacks, implicit reasoning about why something matters, and assertions that need mental models to make sense, distinguishing what's obvious to experts from what's invisible to newcomers.
-
Check for skipped steps - In procedures, verify each step can be completed based on information provided so far. In concepts, watch for logical leaps where reasoning chains are compressed, especially marked by words like clearly, obviously, or simply, which usually signal places that aren't clear or simple to readers.
-
Surface implicit assumptions - Identify unstated prerequisites, unquestioned mental models, and domain-specific conventions the writer follows without explaining, recognizing that what's implicit to experts is invisible to novices and creates gaps writers don't notice.
-
Test prerequisite declarations - When prerequisites are stated, verify the explanation stays within those bounds without secretly requiring additional knowledge, and check if prerequisites are specific enough to help readers actually assess their readiness rather than using vague terms that mean different things to different people.
Examples
Recipe with skipped technique
I'm reviewing a baking recipe that says "Step 3: Fold the egg whites into the batter. Step 4: Pour into prepared pan." For someone who bakes regularly, "fold" is a specific technique they know. For someone following their first recipe, "fold" might mean the same as "mix" or "stir." I trace what knowledge step 3 requires. The instruction names a technique but doesn't explain it. Someone following these steps would reach step 3 and either guess (probably stirring, which deflates the egg whites and ruins the texture) or stop, confused. The recipe assumes knowledge of folding technique without stating it as a prerequisite or explaining it in the instructions. Between step 3 and step 4 is missing information: what folding means and how to do it. The gap emerges from compression of expert knowledge into a single verb that carries technique invisible to beginners. I note this needs either a brief explanation of folding or a link to foundational technique, with prerequisites updated to say "familiarity with basic baking techniques" instead of just "beginner-friendly."
Tutorial with hidden prerequisites
I'm reviewing a tutorial titled "Building Your First API" that claims to be for beginners. The opening says "First, initialize your project with npm init." I stop here because npm hasn't been introduced. The tutorial assumes readers know what npm is, have it installed, and understand package managers. For someone who's never used Node.js, this first instruction is already impossible to complete. The gap isn't in the tutorial content itself but in the unstated prerequisites. The title suggests true beginners, but execution assumes intermediate knowledge. I note the tutorial needs either to establish what npm is and guide installation, or to revise the title and prerequisites to accurately reflect who can actually follow it. The gap emerges from mismatch between promised and actual audience.
Logical jump in explanation
I'm reading an explanation of why caching improves performance: "When you cache data, you store it closer to the user. This means response times improve by up to 80%." I trace the logical connection. Sentence one says caching stores data closer. Sentence two claims this improves response times dramatically. But the connection between closer and faster isn't established. Someone who already understands network latency finds this obvious, but someone learning needs the intermediate steps: closer storage means shorter physical distance, shorter distance means less network travel time, less travel time means faster responses. The writer compressed expert understanding into a claim that seems self-evident to them but represents a logical gap to learners. The specific percentage without supporting explanation makes it worse, appearing to pull numbers from nowhere. I flag this as needing the reasoning chain made explicit.
Documentation using unexplained jargon
I'm examining API documentation that says "Authenticate using OAuth 2.0 with bearer tokens in the authorization header." For readers familiar with authentication, this is clear and concise. For readers learning this, it contains at least four concepts used without definition: OAuth 2.0, bearer tokens, authorization header, and the relationship between all three. Each term is used as if its meaning is shared knowledge. I identify this as multiple terminology gaps creating a comprehension barrier. Someone might recognize authentication and authorization as security-related but have no path from that general understanding to the specific instruction. The documentation works for experienced developers looking up syntax but fails for developers trying to understand concepts. The gap is between who the documentation appears to serve and who it actually serves.
