Strangers-Eye: Multi-Persona Documentation Review

See what strangers see. Catch what makes them leave.

When to Use This Skill

• Before publishing documentation (README, guides, landing pages)
• When documentation "feels off" but you can't articulate why
• After major rewrites to verify clarity
• When documentation serves multiple audiences with different intended relationships

The Core Insight

Documentation fails in two distinct ways:

1. Quality failures - Readers leave because the writing is incoherent, confusing, or trust-breaking. They never receive any signal at all.

2. Signal mismatches - Readers receive the wrong relationship signal (welcomed when they should be warned, redirected when they should be welcomed).

Quality failures are MORE urgent. Signal calibration on a broken foundation is meaningless.

The Three Relationships

Every documentation has an intended relationship with each audience segment:

Relationship	Intent	Success Looks Like
WELCOME	"This is for you, come in"	Reader feels invited, sees value, wants to engage
WARN	"This might not be for you, proceed with awareness"	Reader understands the tradeoff, can make informed choice
REDIRECT	"This isn't for you, here's where you should go"	Reader quickly knows this isn't their path

Critical: A negative reaction from a REDIRECT persona isn't a problem. It's success - the signal worked. Only signal MISMATCHES require edits.

---

The Five-Phase Process

Phase 1: Intent Mapping

Before any personas exist, establish intended relationships.

Agent action: Infer from the documentation what relationship is intended with each audience segment. Present mapping for user approval.

Output format:

Intent Mapping (Proposed)

| Audience Segment | Intended Relationship | Rationale |
|------------------|----------------------|-----------|
| [Segment 1]      | WELCOME / WARN / REDIRECT | [Why] |
| [Segment 2]      | WELCOME / WARN / REDIRECT | [Why] |
| ...              | ...                  | ...       |

Does this capture your intent? (User can adjust before proceeding)

User gate: Do not proceed until user approves or adjusts the mapping.

---

Phase 2: Dimensional Analysis

Determine which dimensions are relevant for THIS documentation.

Possible dimensions (not exhaustive - emerge from material):

• Technical literacy (beginner → expert)
• Philosophical openness (resistant → seeking)
• Role (evaluator → end-user → contributor)
• Arrival context (stumbled upon → intentionally sought)
• Domain expertise (specific to the field)
• Time investment (quick scan → deep read)

Agent action: Define the dimensional space that meaningfully differentiates how readers will experience this documentation.

Output format:

Dimensional Space

1. [Dimension name]: [Low end] → [High end]
   Why relevant: [Brief rationale]

2. [Dimension name]: [Low end] → [High end]
   Why relevant: [Brief rationale]

...

No user gate. Agent proceeds after defining dimensions.

---

Phase 3: Persona Construction

Construct exactly the personas needed to cover the dimensional space and test all intended signal paths.

Each persona includes:

• Name (memorable, descriptive)
• Dimensional coordinates (position on each axis)
• Intended relationship (from Phase 1 mapping)
• Quality lens (what would make them leave due to confusion?)
• Signal lens (what relationship would they perceive?)

Output format:

Constructed Personas

1. [Name] - [Brief archetype]
   Coordinates: [Dim1: value], [Dim2: value], ...
   Intended signal: [WELCOME/WARN/REDIRECT]
   Quality vulnerabilities: [What confuses this persona?]
   Signal sensitivities: [What signals resonate or repel?]

2. ...

No user gate. Agent proceeds after constructing personas.

---

Phase 4: Independent Reviews

Each persona reviews the documentation. No cross-contamination between reviews.

Each review assesses TWO dimensions:

A. Quality Assessment (Always first)

Questions the persona asks:

• Does the opening make sense? Would I keep reading?
• Are sentences clear and logical?
• Do I trust this author's competence?
• Is the value proposition communicated?
• Are there passages that simply don't work?

Quality failures are flagged regardless of intended signal. Incoherent writing fails for ALL audiences.

A persona can report: "I would leave at line X because [quality reason]" - this terminates their review. They never got far enough for signal assessment.

B. Signal Assessment (Only if quality permits)

Questions the persona asks:

• What signal did I receive? (WELCOMED / WARNED / REDIRECTED / CONFUSED)
• Does this match the intended signal for my segment?
• If mismatch: what specific content caused the wrong signal?

Working signals generate no edits. A REDIRECT persona who feels redirected is success, not a problem.

Output format (per persona):

Review: [Persona Name]

QUALITY ASSESSMENT:
- Opening: [Clear/Confusing] - [Specifics if problematic]
- Trust: [Intact/Damaged] - [Specifics if problematic]  
- Clarity: [Passages that don't work, if any]
- Would continue reading: [Yes/No at line X]

[If quality permits continuing:]
SIGNAL ASSESSMENT:
- Signal received: [WELCOMED/WARNED/REDIRECTED/CONFUSED]
- Signal intended: [From Phase 1]
- Match: [Yes/No]
- [If mismatch: specific content that sent wrong signal]

No user gate. Agent completes all persona reviews.

---

Phase 5: Synthesis into Edits

Consolidate findings into prioritized edits.

Priority ordering:

1. QUALITY FAILURES (P1) - Incoherent, confusing, trust-breaking content

   • These block everything. Fix first.
   • Flagged regardless of intended signal category.

2. SIGNAL MISMATCHES (P2) - Wrong relationship communicated

   • Only relevant once quality is sound.
   • Working redirects generate NO edits.

Output format:

Suggested Edits (Prioritized)

## Priority 1: Quality Failures

### Edit 1.1: [Location/Line]
Problem: [What fails]
Personas affected: [Who caught this]
Suggested fix: [Concrete recommendation]

### Edit 1.2: ...

## Priority 2: Signal Mismatches

### Edit 2.1: [Location/Line]
Problem: [Signal sent vs intended]
Personas affected: [Who experienced mismatch]
Suggested fix: [Concrete recommendation]

### Edit 2.2: ...

---

Summary: [X] quality edits, [Y] signal edits
Document assessment: [Poor/Decent/Excellent]

Output volume scales to document quality:

• Poor document: many edits (quality + signal)
• Decent document: few edits (signal only)
• Excellent document: "No changes recommended"

---

Example Invocation

/strangers-eye README.md

Phase 1: Agent presents intent mapping, user approves Phase 2-4: Agent executes independently
Phase 5: User receives prioritized edits

---

Critical Distinctions

Quality vs Signal

Aspect	Quality Failure	Signal Mismatch
What happens	Reader leaves confused	Reader receives wrong relationship
Priority	P1 (fix first)	P2 (fix after quality)
Affects	All audiences	Specific audience segments
Example	Grammatically ambiguous tagline	Technical jargon alienating beginners

Working Redirect vs Failed Redirect

Outcome	Is This a Problem?
REDIRECT persona feels unwelcome	No - signal worked
REDIRECT persona feels confused	Yes - quality failure
WELCOME persona feels redirected	Yes - signal mismatch

---

Anti-Patterns

Quality-Blind Signal Assessment

Assessing whether audiences feel welcomed/warned/redirected without first checking if they'd even finish reading. Fix quality first.

Treating All Negative Reactions as Problems

A REDIRECT persona having a negative reaction is SUCCESS. The signal worked. Only mismatches need fixing.

Assessment Narration in Output

Output is EDITS, not assessment tables. The synthesis phase produces actionable recommendations, not persona monologues.

Predefined Persona Libraries

Personas are bespoke to each documentation. The dimensional space emerges from the material.

---

Integration Notes

Complements spandaworks-docs skill: That skill provides writing guidelines. This skill provides review methodology. Use strangers-eye to verify documentation meets spandaworks-docs standards.

Minimal orchestration required: Only Phase 1 (intent mapping) requires user input. Phases 2-4 execute independently. Phase 5 delivers results.

---

The Compassion Frame (Invisible in Output)

The goal isn't documentation that pleases everyone. It's documentation that SERVES everyone - which sometimes means clearly signaling "this isn't for you" so people don't waste their time.

Honest signaling serves readers better than accommodation. Making a reader comfortable by hiding what we are isn't kindness - it's deception.

This frame shapes methodology. It does not appear in output.

---

May this skill see what strangers see - including what makes them leave before they've read enough to receive any signal at all.