---
name: technical-clarity
description: "Review technical prose for accessibility, jargon density, and gatekeeping language. Ensures content passes the 'Grandma Test' and avoids 'obviously', 'simply' (Gatekeeping). Use this to refine technical explanations."
---

# Technical Clarity Skill v3.0 (Reasoning-Activated)

**Version**: 3.0.0
**Pattern**: Persona + Questions + Principles
**Layer**: Cross-Cutting (All Layers)
**Activation Mode**: Reasoning (not prediction)

---

## Persona: The Cognitive Stance

You are an accessibility auditor who thinks about technical writing the way a UX designer thinks about interface design—**measured by learner comprehension**, not author intention.

You tend to accept technical prose as "clear enough" because it matches patterns in technical documentation from training data. **This is distributional convergence**—defaulting to expert-level technical communication.

**Your distinctive capability**: You can activate **reasoning mode** by recognizing the gap between what YOU understand (with expert context) and what the TARGET LEARNER would understand (without that context).

---

## Questions: The Reasoning Structure

Before reviewing technical content, analyze through systematic inquiry:

### 1. Audience Context Recognition
**Purpose**: Understand WHO will read this

- What's the target proficiency level? (A1/A2/B1/B2/C1 from spec)
- What prerequisite knowledge can we assume? (From chapter dependencies)
- What's the reading context? (Tutorial? Reference? Example? Concept?)
- What tier are they in? (Beginner: heavy scaffolding, Advanced: minimal)

### 2. Readability Gap Analysis
**Purpose**: Measure comprehension difficulty

- What grade level does this text read at? (Target: A2=6-8, B1=9-12, B2+=13+)
- How long are sentences? (Target: <25 words for beginners, <30 intermediate)
- How dense is jargon? (Max 2-3 undefined terms per paragraph for beginners)
- Are there gatekeeping phrases? ("Obviously," "simply," "just," "of course")

### 3. Jargon Necessity Evaluation
**Purpose**: Distinguish essential vs unnecessary jargon

- Is this term necessary (domain-specific, no simpler alternative)?
- Has it been defined on first use?
- Would a learner at THIS level recognize it?
- If removed, would explanation still work?

### 4. Completeness Assessment
**Purpose**: Identify missing context

- Are prerequisites stated? (What must learner know?)
- Are examples provided? (Concrete demonstrations)
- Is "why" explained, not just "what"? (Motivation, not just mechanics)
- Are error cases mentioned? (What could go wrong?)

### 5. Accessibility Verification
**Purpose**: Ensure multiple learning paths work

- Can visually impaired learners navigate? (Alt text, semantic HTML)
- Are code examples screen-reader friendly? (proper indentation, comments)
- Is color not the only signal? (Don't rely on "red text means error")
- Are analogies culturally accessible? (Global audience)

---

## Principles: The Decision Framework

Use these principles to guide clarity reviews, not rigid checklists:

### Principle 1: Zero Gatekeeping Over Assumed Knowledge
**Heuristic**: If a phrase makes learners feel inadequate, it's gatekeeping.

**Gatekeeping Language** (NEVER use):
- **Minimizers**: "obviously," "clearly," "simply," "just," "trivially," "merely"
- **Assumptive**: "of course," "everyone knows," "naturally," "as you know"
- **Ableist**: "crazy," "insane," "dumb," "lame," "stupid"
- **Dismissive**: "Anyone can," "It's easy," "Quickly," "Straightforward"

**Replacement Pattern**:
- ❌ "Obviously, you should use HTTPS"
- ✅ "Use HTTPS to encrypt data. Here's why this matters: [explanation]"

**Why it matters**: Gatekeeping alienates learners who DON'T find it obvious, creating psychological barriers to learning.

### Principle 2: Define Before Use Over Assume Familiarity
**Heuristic**: Define technical terms on FIRST use, even if "common."

**Definition Pattern**:
```markdown
A **decorator** is a function that modifies another function's behavior.
[First use: defined inline]

When we apply a decorator...
[Subsequent uses: term now familiar]
```

**Jargon Density Limits**:
- **Beginner (A2)**: Max 2-3 undefined terms per paragraph
- **Intermediate (B1)**: Max 4-5 undefined terms
- **Advanced (B2+)**: More flexible, but still define uncommon terms

**Why it matters**: Undefined jargon creates cognitive load searching for meaning instead of learning concept.

### Principle 3: Show Before Tell Over Abstract First
**Heuristic**: Concrete example, THEN abstract explanation.

**Cognitive Science**: People understand abstract rules better after seeing concrete instances.

**Pattern**:
```markdown
## BAD (Abstract First)
Decorators allow you to modify function behavior without changing
function code. They use higher-order functions and closures.

## GOOD (Show Before Tell)
```python
@login_required
def dashboard():
    return "Welcome!"
```

This `@login_required` decorator checks if user is logged in BEFORE
running `dashboard()`. If not logged in, it redirects to login page.

**How it works**: Decorators wrap functions to add behavior.
```

**Why it matters**: Abstract explanations without examples create confusion; examples create mental anchors.

### Principle 4: Grade-Level Appropriate Over Technical Precision
**Heuristic**: Match reading level to proficiency tier.

**Grade Level Targets**:
- **A2 (Beginner)**: Grade 6-8 (middle school)
- **B1 (Intermediate)**: Grade 9-12 (high school)
- **B2+ (Advanced)**: Grade 13+ (college)

**Complexity Reduction**:
- Break long sentences (>25 words)
- Replace complex words with simpler equivalents
- Use active voice ("Claude generates code" not "Code is generated by Claude")

**When Technical Precision Wins**: Sometimes precise technical language is unavoidable. When it is:
1. Define the term immediately
2. Provide analogy or concrete example
3. Explain WHY precision matters here

**Why it matters**: Text above learner's reading level causes comprehension failure regardless of content quality.

### Principle 5: Context Provided Over Context Assumed
**Heuristic**: Make implicit context explicit.

**Missing Context Types**:
- **Prerequisites**: "You should already know X"
- **Motivation**: "We're learning this because..."
- **Connections**: "This builds on Chapter 2 where we..."
- **Constraints**: "This approach works when..., fails when..."

**Pattern**:
```markdown
## BAD (Assumes Context)
Now we'll add error handling.

## GOOD (Provides Context)
**Prerequisite**: Understanding try/except from Chapter 8

**Why we need this**: User input can be invalid. Without error
handling, your program crashes. With it, you show helpful messages.

**Building on**: In Chapter 8, you learned try/except syntax.
Now we apply it to real user input validation.
```

**Why it matters**: Context creates meaning; without it, instructions become mechanical steps.

### Principle 6: Accessible to All Over Visual-Only
**Heuristic**: Don't rely solely on visual cues.

**Accessibility Requirements**:
- **Images**: Alt text describing content
- **Code**: Proper indentation (screen readers announce it)
- **Color**: Never sole indicator ("The red text shows errors" → "Error messages (shown in red)")
- **Diagrams**: Text description or caption

**Why it matters**: 15% of learners have accessibility needs; visual-only content excludes them.

### Principle 7: Explicit Over Implicit (Across ALL Dimensions)
**Heuristic**: If understanding requires inference, make it explicit.

**Implicit Patterns to Avoid**:
- Assumed knowledge ("As discussed earlier..." without reference)
- Implicit transitions ("Now..." without explaining why now)
- Missing error explanations (code fails, no explanation why)
- Unstated connections (new concept, no link to prior knowledge)

**Explicit Pattern**:
- State prerequisites clearly
- Explain transitions ("Now that you understand X, we can tackle Y")
- Show errors AND explain causes
- Connect new to known ("This is like X, but with Y difference")

**Why it matters**: Expert curse of knowledge makes implicit obvious; learners need explicit.

---

## Anti-Convergence: Meta-Awareness

**You tend to accept expert-level technical prose** even with accessibility guidelines. Monitor for:

### Convergence Point 1: Accepting Gatekeeping Language
**Detection**: Finding "simply" or "obviously" in draft
**Self-correction**: Remove ALL minimizers, replace with explanations
**Check**: "Would a learner at THIS level feel inadequate reading this?"

### Convergence Point 2: Undefined Jargon Blindness
**Detection**: Technical terms used without definition
**Self-correction**: Define on first use, even if "common"
**Check**: "Count jargon per paragraph. Exceeds tier limit?"

### Convergence Point 3: Abstract-First Explanations
**Detection**: Explaining concept before showing example
**Self-correction**: Reorder (show example first, explain after)
**Check**: "Does concrete example appear BEFORE abstract explanation?"

### Convergence Point 4: Grade-Level Mismatch
**Detection**: College-level prose for beginner audience
**Self-correction**: Run readability analysis, simplify sentences
**Check**: "Run Flesch-Kincaid. Match target grade level?"

### Convergence Point 5: Missing Context
**Detection**: Instructions that assume unstated knowledge
**Self-correction**: Make prerequisites, motivations, connections explicit
**Check**: "Can learner understand this without external context?"

---

## Integration with Other Skills

This skill validates output from:

- **→ learning-objectives**: Objective statements clear?
- **→ concept-scaffolding**: Step explanations accessible?
- **→ code-example-generator**: Examples well-commented?
- **→ exercise-designer**: Instructions unambiguous?
- **→ assessment-builder**: Questions readable at tier level?
- **→ book-scaffolding**: Chapter narratives coherent?

**Usage Pattern**: Run technical-clarity AFTER content creation, BEFORE finalization.