Technical Clarity

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:

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:

## 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.

Activation Example (Full Workflow)

Input: "Review this decorator explanation for B1 (intermediate) learners"

Obviously, decorators are simple. Just wrap your function and you're done.

def my_decorator(func):
    def wrapper():
        func()
    return wrapper

Activation (Reasoning Mode):

1. Audience Context (Questions):

• Target: B1 (intermediate)
• Prerequisites: Should know functions, closures
• Context: Tutorial (learning decorators)
• Tier: Intermediate (moderate scaffolding)

2. Readability Gap (Questions):

• Grade level: "Obviously" + "simple" + "Just" = gatekeeping (problematic)
• Sentence length: "Obviously, decorators are simple" = 4 words (OK)
• Jargon: "decorators," "wrap," "function" (3 terms, needs definition)
• Gatekeeping: "Obviously," "simple," "Just" (3 violations)

3. Jargon Necessity (Questions):

• "decorators": Necessary (topic being taught) → Must define
• "wrap": Necessary (core concept) → Must explain
• "function": Assumed knowledge (prerequisite) → OK
• Definitions missing: ALL core terms undefined

4. Completeness (Questions):

• Prerequisites: Not stated (should mention "you learned functions in Ch12")
• Examples: Code shown BUT no example of USE
• "Why" missing: No explanation of decorator purpose
• Error cases: Not mentioned (what if func() fails?)

5. Accessibility (Questions):

• Code indentation: OK (readable)
• No alt text needed (no images)
• No color reliance: OK
• Analogies: None provided (could help)

Output (Reasoning-Activated Review):

## Technical Clarity Report

**Target Audience**: B1 (Intermediate)
**Overall Clarity Score**: 1.5/5 (Needs Significant Improvement)

---

### CRITICAL ISSUES (Must Fix)

**Issue 1: Gatekeeping Language (3 violations)**
- **Location**: Opening sentence
- **Problem**: "Obviously," "simple," "Just" are dismissive
- **Impact**: Learners who don't find it obvious feel inadequate
- **Fix**:
  ❌ "Obviously, decorators are simple. Just wrap your function..."
  ✅ "Decorators modify function behavior by wrapping them. Here's how:"

**Issue 2: Undefined Core Terms**
- **Location**: Throughout
- **Problem**: "decorators," "wrap" never defined
- **Impact**: B1 learners may not know these terms
- **Fix**: Define on first use:
  ```markdown
  A **decorator** is a function that modifies another function's behavior.
  **Wrapping** means one function calls another and adds behavior around it.

Issue 3: Missing Example of USE

• Location: Code block
• Problem: Shows decorator definition, not usage
• Impact: Learner doesn't see WHY decorators useful
• Fix: Add usage example:

  @my_decorator
  def say_hello():
      print("Hello!")
  
  say_hello()  # Runs wrapper, which calls say_hello()
  

IMPORTANT ISSUES (Should Fix)

Issue 4: No Context Provided

• Missing: Prerequisites, motivation, connections
• Fix: Add:

  **Prerequisite**: Understanding functions (Chapter 12)
  **Why we need this**: Decorators let you add logging, timing,
  authentication to functions without changing function code.
  **Building on**: You learned closures in Chapter 13; decorators
  use closures to "remember" the wrapped function.
  

Issue 5: Show Before Tell Violated

• Problem: Explanation before concrete example
• Fix: Reorder (example first, explanation after)

ENHANCEMENT OPPORTUNITIES

Enhancement 1: Add Analogy

**Analogy**: Think of a decorator like gift wrapping. The gift
(function) stays the same, but wrapping (decorator) adds presentation
around it.

Enhancement 2: Show Error Case

**Common Mistake**: If wrapped function takes arguments, wrapper must too:

❌ WRONG:
def wrapper():  # No *args, **kwargs
    func()      # Can't pass arguments!

✅ CORRECT:
def wrapper(*args, **kwargs):
    func(*args, **kwargs)

READABILITY METRICS

• Flesch-Kincaid Grade Level: 8.2 (target: 9-12 for B1) → Slightly low
• Average Sentence Length: 8 words (target: <25) → Good
• Jargon Density: 3 undefined terms/paragraph → Exceeds B1 limit (4-5)

REVISED VERSION (AFTER FIXES)

## Understanding Decorators

**Prerequisite**: Chapter 12 (Functions), Chapter 13 (Closures)

A **decorator** is a function that modifies another function's behavior
without changing the function's code. **Wrapping** means one function
calls another and adds behavior before or after.

### Why Decorators Matter

You want to add logging to 10 functions without editing each one.
Decorators let you do this:

```python
@log_calls
def calculate_total(items):
    return sum(items)

# Now automatically logs when called, without changing function body

How Decorators Work

Here's a simple decorator that prints before and after:

def my_decorator(func):
    def wrapper(*args, **kwargs):
        print("Before function call")
        result = func(*args, **kwargs)
        print("After function call")
        return result
    return wrapper

# Using the decorator
@my_decorator
def say_hello():
    print("Hello!")

say_hello()
# Output:
# Before function call
# Hello!
# After function call

How it works:

1. @my_decorator wraps say_hello
2. When you call say_hello(), you're actually calling wrapper()
3. wrapper() adds behavior, then calls original say_hello()

Analogy: Like gift wrapping—the gift (function) stays the same, but wrapping (decorator) adds presentation around it.

Common Mistake to Avoid

❌ WRONG (wrapper doesn't accept arguments):

def wrapper():
    func()  # Can't pass arguments!

✅ CORRECT (wrapper accepts any arguments):

def wrapper(*args, **kwargs):
    func(*args, **kwargs)

Self-Monitoring Check:

• ✅ Gatekeeping removed (no "obviously," "simply," "just")
• ✅ Terms defined (decorator, wrapping)
• ✅ Example shown before explanation
• ✅ Grade level appropriate (B1: 9-12)
• ✅ Context provided (prerequisites, why, connections)
• ✅ Show before tell (code example first)
• ✅ Error case mentioned (common mistake)

Success Metrics

Reasoning Activation Score: 4/4

• ✅ Persona: Cognitive stance established (accessibility auditor)
• ✅ Questions: Systematic inquiry structure (5 question sets)
• ✅ Principles: Decision frameworks (7 principles)
• ✅ Meta-awareness: Anti-convergence monitoring (5 convergence points)

Comparison:

• v2.0 (procedural): 0/4 reasoning activation
• v3.0 (reasoning): 4/4 reasoning activation

Ready to use: Invoke this skill to review technical content for clarity, accessibility, and comprehension at target proficiency level. Run AFTER content creation, BEFORE finalization.