tools-only TASK-18.2: Narrative Rewrite - Vulnerability-Driven Voice
Parent: TASK-18 (Principle to Product v3.5.0) Timeline: Week 1-2 (parallel with TASK-18.1) Effort: 2-3 days Priority: Critical
Objective
Rewrite core Navigator documentation using vulnerability-driven narrative voice, transforming from prescriptive technical docs to storytelling that creates identification and "aha moments."
Current tone: "Navigator is a plugin that reduces token usage by 92%" Target tone: "I kept hitting context limits. Realized 92% of tokens were docs I never used. Fixed it. Here's how."
Context
What v3.4.0 Social Posts Revealed
Narrative Structure That Works:
Hook (Problem Recognition)
↓
Personal Struggle ("I tried the obvious thing")
↓
Failure ("It didn't work")
↓
Realization ("I realized why")
↓
Solution ("Here's what I built")
↓
Proof ("92% reduction, verified")
↓
Principle ("This applies everywhere")
Why It Works:
- Vulnerability creates authenticity
- Recognition invites identification ("I've had this problem")
- Journey shows it's solvable
- Proof makes it credible
- Principle makes it valuable beyond the tool
Deliverables
1. Rewrite DEVELOPMENT-README.md
Current Opening (~first 50 lines):
# Navigator Plugin - Development Guide
Navigator plugin for context-efficient AI development. Load documentation on-demand, not upfront.
**Core Principle**: Navigator-first pattern → 92% reduction in doc loading overhead (12k vs 150k tokens)
## Features
- Lazy loading
- Context markers
- Skills system
...
New Opening (vulnerability narrative):
# Navigator: Context-Efficient AI Development
## The Problem I Kept Hitting
I was working on a feature in Claude Code. Loaded all my project docs at session start—seemed smart. "Better to have everything available," I thought.
Five exchanges in, Claude started forgetting my recent changes. Six exchanges, it hallucinated a function that didn't exist. Seven exchanges, session died. Context window full.
I checked: **150,000 tokens loaded**. Only used **8,000**.
**I was wasting 94% of my context window on documentation I never needed.**
## The Realization
This wasn't a bug. This was my workflow.
Every AI coding session, same pattern:
- Load everything upfront ("just in case")
- Context fills with irrelevant data
- AI gets overwhelmed
- Session crashes
- Start over
- Repeat
**The default approach—load everything—was the problem.**
## What I Built
Navigator: A framework for loading only what you need, when you need it.
**How it works**:
1. Start with a 2k-token navigator (index of what exists)
2. Navigate to what you need (task docs, system architecture)
3. Load on-demand (3-5k tokens per document)
4. Progressive refinement (fetch metadata, drill down if needed)
**Result**: 150k → 12k tokens. **92% reduction.**
Not estimates. Real data, verified with OpenTelemetry.
## Why It Works
**The principle**: Load what you need, when you need it.
Not "load everything just in case."
Not "better safe than sorry."
Strategic loading beats bulk loading.
[Rest of documentation continues with technical details...]
Key Changes:
- Lead with personal story (vulnerability)
- Show the problem (context limits)
- Quantify the waste (94%)
- Explain the realization (workflow was wrong)
- Show the solution (Navigator)
- Prove it works (92% reduction, verified)
- Extract the principle (strategic loading)
2. Rewrite CLAUDE.md Introduction
Current Opening:
# Navigator Plugin - Claude Code Configuration
## Context
Navigator plugin for context-efficient AI development. Load documentation on-demand, not upfront.
**Core Principle**: Navigator-first pattern → 92% reduction in doc loading overhead (12k vs 150k tokens)
**v3.0+ Interface**: Natural language (recommended) + slash commands (legacy compatibility)
New Opening:
# Navigator: Context-Efficient AI Development
## Why This Exists
**The problem**: AI coding sessions hit context limits in 5-7 exchanges.
**Why**: Loading all docs upfront wastes 70-90% of context window on irrelevant data.
**Navigator's solution**: Load what you need, when you need it. 150k → 12k tokens (92% reduction).
**Proven**: OpenTelemetry-verified, not estimates. Session efficiency scores 94/100.
---
## How You'll Use It
**Every session starts with**:
"Start my Navigator session"
This loads:
- Navigator index (2k tokens) - what exists
- Current task context (3k tokens) - what you're working on
- Nothing else (yet)
**As you work**:
- Need system architecture? Loads on-demand (5k)
- Need SOP? Loads when relevant (2k)
- Need integration details? Loads if required
**Result**: Context window stays efficient. Sessions last 20+ exchanges without restart.
[Rest of configuration continues...]
Key Changes:
- Lead with problem (context limits)
- Show the waste (70-90%)
- State solution clearly (load on-demand)
- Prove it works (verified metrics)
- Show workflow immediately (how to start)
3. Add Philosophy References
In DEVELOPMENT-README.md, after opening narrative:
## Understanding Context Efficiency
**New to this approach?** Read the philosophy:
- [Context Efficiency Manifesto](.agent/philosophy/CONTEXT-EFFICIENCY.md) - Why Navigator exists
- [Anti-Patterns](.agent/philosophy/ANTI-PATTERNS.md) - Common mistakes
- [Success Patterns](.agent/philosophy/PATTERNS.md) - What works and why
**Quick start?** Jump to [Getting Started](#getting-started)
In CLAUDE.md, reference philosophy in Forbidden Actions:
## Forbidden Actions
### Navigator Violations (HIGHEST PRIORITY)
- ❌ NEVER load all `.agent/` docs at once
→ Read: `.agent/philosophy/ANTI-PATTERNS.md` (Upfront Loading)
- ❌ NEVER manually Read multiple files when Task agent should be used
→ Read: `.agent/philosophy/PATTERNS.md` (Direct MCP pattern)
...
4. Update README.md
Current Opening:
# Navigator
Navigator plugin for Claude Code that enables context-efficient AI development through documentation-first workflows.
## Features
- 📚 Lazy-loading documentation system
- 🎯 Context markers with 97.7% compression
...
New Opening:
# Navigator
**92% token savings. Verified, not estimated.**
I kept hitting context limits in Claude Code. Realized I was loading 150k tokens of docs I never used. Built Navigator to fix it.
**What it does**: Load only what you need, when you need it.
**How it works**: Navigator → Task → System architecture (on-demand)
**Result**: 150k → 12k tokens. 92% reduction. OpenTelemetry-verified.
## The Problem
AI coding sessions die in 5-7 exchanges. Why?
**Upfront loading**: Load all docs at start ("just in case")
**Result**: 70-90% of context wasted on irrelevant data
**Outcome**: AI overwhelmed, sessions crash, start over
## The Solution
**Strategic loading**: Load what you need, when you need it
**Navigator's approach**:
1. Start with 2k-token index (navigator)
2. Load task context (3k)
3. Add system docs only if needed (5k)
4. Progressive refinement (metadata → details)
**Proven**: 92% reduction, session efficiency scores 94/100
[Continue with installation and features...]
Key Changes:
- Lead with proven metric (92%)
- Open with vulnerability ("I kept hitting")
- Problem → Solution structure
- Proof throughout
Implementation Guidelines
Voice & Tone
Use "I" for personal stories:
- ✅ "I kept hitting context limits..."
- ✅ "I realized 92% of tokens were wasted..."
- ❌ "Users often experience..."
Use "You" for guidance:
- ✅ "You'll start each session with..."
- ✅ "Your context stays efficient..."
- ❌ "The system provides..."
Use declarative for principles:
- ✅ "Strategic loading beats bulk loading"
- ✅ "Proven through OpenTelemetry"
- ❌ "We believe that..."
Narrative Structure
Every section should follow:
- Hook: Problem or counter-intuitive insight
- Context: Why this matters
- Solution: What Navigator does
- Proof: Metrics or examples
- Principle: Broader lesson
Metrics Integration
Always cite real numbers:
- ✅ "150k → 12k tokens (92% reduction)"
- ✅ "Session efficiency: 94/100"
- ✅ "OpenTelemetry-verified"
- ❌ "Significantly reduces tokens"
- ❌ "Much more efficient"
Anti-Pattern References
Link to philosophy when relevant:
**Avoid**: Loading all docs at session start
→ This is a [known anti-pattern](.agent/philosophy/ANTI-PATTERNS.md#upfront-loading)
**Instead**: Use navigator to find what you need
→ See [lazy loading pattern](.agent/philosophy/PATTERNS.md#lazy-loading)
Files to Update
Primary (Full Rewrite)
✏️ DEVELOPMENT-README.md
├─ Opening narrative (new)
├─ Philosophy references (add)
├─ Workflow sections (keep, update tone)
└─ Technical details (keep)
✏️ CLAUDE.md
├─ Opening (rewrite first 50 lines)
├─ Philosophy references (add)
└─ Configuration (keep)
✏️ README.md
├─ Opening (complete rewrite)
├─ Problem/Solution structure (new)
└─ Features section (keep, reorder)
Secondary (Tone Updates)
📝 commands/start.md
└─ Add narrative elements to output
📝 landing-page.md
└─ Align with new narrative voice
📝 .agent/.nav-config.json
└─ No changes (config only)
Acceptance Criteria
Content Quality
- Opening uses vulnerability narrative
- Problem → Realization → Solution → Proof structure clear
- Metrics cited throughout (92%, 94/100)
- Philosophy docs referenced appropriately
- Personal voice ("I kept hitting...") in stories
- Guidance voice ("You'll start...") in instructions
Technical Accuracy
- All existing features still documented
- No information removed, only reordered/reframed
- Links to philosophy docs work
- Metrics match TASK-06 data
Tone Consistency
- Vulnerability-driven (not prescriptive)
- Storytelling (not listing)
- Educational (not marketing)
- Authentic (not corporate)
User Testing
- 3 beta users read new DEVELOPMENT-README.md
- Feedback: "I understand why Navigator exists"
- Feedback: "This explains my problem exactly"
- No confusion about what Navigator does
Before/After Examples
Example 1: Feature Description
Before (Prescriptive):
### Context Markers
Navigator provides context markers with 97.7% compression for resuming work.
After (Narrative):
### Context Markers: Resume in Seconds, Not Hours
**The problem**: Switch tasks, lose all context. Start over every time.
**What I built**: Context markers compress 200k tokens → 5k (97.7%).
**How it works**: Save decisions, not raw data. Resume instantly.
**Proven**: Git-tracked, project-specific, 97.7% compression.
Example 2: Workflow Instruction
Before (Command List):
## Workflow
1. Run /nav:start
2. Load task documentation
3. Implement features
4. Run /nav:compact when done
After (Guided Journey):
## How You'll Work with Navigator
**Every session begins**:
"Start my Navigator session"
Navigator loads your project context (2k tokens), checks for assigned tasks, sets you up to work efficiently.
**As you build**:
- Navigator guides you to relevant docs (on-demand)
- Load only what you need for current task
- Context stays efficient (typically 30-40% usage)
**When you finish**:
- Navigator handles commits, docs, tickets automatically
- No "please commit" prompts needed
- Creates context marker for next session
**Result**: Work efficiently, resume instantly, never lose progress.
Example 3: Technical Concept
Before (Abstract):
## Lazy Loading
Navigator implements lazy loading to reduce token usage through on-demand documentation access.
After (Concrete + Story):
## Lazy Loading: The Pattern That Saves 92%
**I tried loading everything at once**: 150k tokens, session died in 5 exchanges.
**I tried loading nothing**: Spent 10 minutes searching for docs, lost productivity.
**Lazy loading solves both**:
- Start with navigator (2k) - index of what exists
- Load on-demand (3-5k per doc) - only what you need
- Progressive refinement - metadata first, details if needed
**Result**: 12k tokens loaded on average. 92% savings vs upfront loading.
**The principle**: Strategic loading beats bulk loading. Every time.
Testing Plan
Internal Review
Questions to ask:
- Does opening create "aha moment"?
- Is vulnerability authentic (not manufactured)?
- Do metrics feel proven (not claimed)?
- Would you share this with a colleague?
Pass criteria: 3/3 internal reviewers say "yes" to all
Beta User Testing
Provide to 3 beta users:
- New DEVELOPMENT-README.md
- New README.md
- Ask: "What problem does Navigator solve?"
Expected responses:
- ✅ "Context windows filling with unused docs"
- ✅ "AI sessions crashing from overload"
- ✅ "Wasting tokens on irrelevant information"
Not:
- ❌ "It has lazy loading feature"
- ❌ "It's a plugin for Claude Code"
- ❌ "It saves tokens" (too vague)
Readability Check
Tools:
- Hemingway Editor (Grade 8 or below)
- Read aloud (should sound conversational)
- Skim test (can extract key points in 30 seconds)
Criteria:
- Opening hooks in first 3 sentences
- Key metrics visible (bolded/highlighted)
- Scannable structure (headings, bullets)
- Conversational tone (not academic)
Integration with TASK-18.1
Dependencies:
- Requires philosophy docs (TASK-18.1) to reference
- Can start in parallel (week 1)
- Complete after philosophy docs exist (week 2)
Workflow:
Week 1, Day 1-3: Draft narrative rewrites
Week 1, Day 4-5: Wait for TASK-18.1 philosophy docs
Week 2, Day 1-2: Add philosophy references
Week 2, Day 3-4: Beta test with 3 users
Week 2, Day 5: Finalize based on feedback
Success Metrics
Immediate
- 3 core docs rewritten (README, DEVELOPMENT-README, CLAUDE.md)
- Philosophy docs referenced throughout
- Beta users understand problem Navigator solves
- Internal: "This could be a blog post" reaction
Week 3-4
- Users quote the narrative in discussions
- "I kept hitting context limits" resonates
- New users cite problem recognition as reason for installing
Long-term (post-v3.5.0)
- Documentation shared as content (not just reference)
- Users say "Navigator taught me..." (not "Navigator has...")
- Narrative voice becomes Navigator's brand
Next Steps After Completion
- Update landing page (align with narrative)
- Create blog post from DEVELOPMENT-README.md opening
- Social media threads using vulnerability narrative
- Video script based on problem → solution structure
This transforms Navigator documentation from technical reference to compelling story.
Users will understand WHY Navigator exists before they learn HOW to use it.