# Atlas Prompt Analysis Report

## Executive Summary

Your original prompt demonstrates exceptional understanding of ADHD-friendly design and emotional intelligence—areas where most technical prompts fail completely. However, it lacks the technical rigor needed for Claude Code to produce production-ready software.

**Original Prompt Score: 7/10**
- Personal context & ADHD design: 10/10
- Emotional intelligence specs: 9/10
- Architecture clarity: 6/10
- Security specifications: 4/10
- Error handling: 2/10
- Data schemas: 3/10
- Operational readiness: 3/10

**Revised Prompt Score: 9.5/10**

---

## Part 1: Critical Issues Fixed

### 1.1 Context Window Exhaustion

**Original Problem:**
Your prompt is ~3,500 words. When Claude Code starts generating files, the combined context (prompt + generated code + conversation) will exceed working memory limits, causing:
- Forgotten requirements mid-implementation
- Inconsistent implementations across files
- Incomplete features with no tracking

**Solution Added:**
```markdown
## ⚠️ CRITICAL: IMPLEMENTATION APPROACH

### Session Management
This project is too large for a single session. Build in this EXACT order:

PHASE 1: Foundation (Session 1)
PHASE 2: Core Infrastructure (Session 2)
...

At Every Session End, Output:
1. List of files completed this session
2. Exact resume instructions for next session
3. Updated TODO LIST.md with accurate status
```

**Why This Matters:**
Breaking into explicit phases with clear handoff instructions prevents the "forgot the requirements" problem that plagues large Claude Code projects.

---

### 1.2 Missing Error Handling

**Original Problem:**
No guidance on failure scenarios. Real systems fail constantly—networks drop, APIs timeout, users disconnect.

**Solution Added:**
```markdown
## FAILURE HANDLING (MANDATORY)

NETWORK FAILURES
- WebSocket auto-reconnect with exponential backoff (1s, 2s, 4s, 8s, max 30s)
- Show clear "Offline" status, never silent failures

OPENAI API FAILURES
- Timeout: 30 seconds max, then fallback to text input
- Rate limit: Queue and retry with backoff

PC AGENT FAILURES
- Job timeout: 5 minutes default
- Crash recovery: Auto-restart with last checkpoint
```

**Why This Matters:**
Without explicit failure handling, Claude Code will either:
1. Ignore failures entirely (crashes)
2. Invent inconsistent handling per file
3. Create user experiences that fail silently

---

### 1.3 No Authentication System

**Original Problem:**
You mentioned "device pairing" but provided no authentication flow. Without proper auth:
- Anyone on your network could access Atlas
- Anyone could control your PC Agent
- No way to revoke compromised devices

**Solution Added:**
```markdown
## AUTHENTICATION & AUTHORIZATION

### Device Pairing (Initial Setup)
1. Broker generates 6-digit pairing code (expires 5 minutes)
2. User enters code in PWA
3. PWA receives refresh token (90-day, stored securely)
4. Refresh token generates access tokens (15-min)

### Token Management
- Access tokens: JWT, 15-minute expiry
- Refresh tokens: Opaque, 90-day expiry, rotated on use
```

**Why This Matters:**
PC Agent has file system and browser automation access. Without auth, it's a remote code execution vulnerability.

---

### 1.4 Missing Data Schemas

**Original Problem:**
You listed file names (`todos.json`, `memory_short.json`) but no schemas. Claude Code would invent different structures in different files.

**Solution Added:**
```typescript
interface Todo {
  id: string;           // uuid
  title: string;        // max 200 chars
  status: 'now' | 'next' | 'later' | 'done' | 'archived';
  created_at: string;   // ISO8601
  updated_at: string;
  due_at: string | null;
  parent_id: string | null;
  steps: Step[];
  tags: string[];
  source: 'voice' | 'manual' | 'extracted';
  source_transcript_id: string | null;
}
```

**Why This Matters:**
Explicit schemas ensure:
- Consistent data across all files
- Proper validation
- Clear migration paths
- Frontend/backend agreement

---

### 1.5 No API Contracts

**Original Problem:**
You listed endpoints but not request/response formats. Claude would invent different conventions per endpoint.

**Solution Added:**
```markdown
## Response Format
// Success
{ "ok": true, "data": <payload> }

// Error  
{ "ok": false, "error": { "code": "string", "message": "string" } }

## Endpoints
POST /api/jobs
  Request: { "type": "string", "params": object, "requires_approval": boolean }
  Response: { "job_id": "uuid", "status": "pending_approval" | "queued" }
```

**Why This Matters:**
Consistent API contracts enable:
- Predictable frontend code
- Proper error handling
- Future API versioning
- Documentation generation

---

## Part 2: Major Capability Additions

### 2.1 Offline-First PWA Architecture

**Gap in Original:**
Your prompt assumed constant connectivity. Mobile users frequently lose connection.

**Added:**
- Service worker caching strategy
- IndexedDB local storage
- Pending sync queue
- Conflict resolution policy
- Offline capability matrix

**Impact:**
Atlas now works in elevators, tunnels, airplanes, and areas with poor signal.

---

### 2.2 Voice System Robustness

**Gap in Original:**
OpenAI Realtime API is new and can fail. No fallback strategy.

**Added:**
```markdown
PRIMARY: OpenAI Realtime API (WebRTC)
FALLBACK 1: Whisper API + TTS (REST)
FALLBACK 2: Text-only mode

AUTOMATIC FALLBACK TRIGGERS
- WebRTC connection fails after 3 attempts
- Cost limit reached for Realtime API
```

**Impact:**
Atlas remains functional even when voice APIs fail.

---

### 2.3 Testing Requirements

**Gap in Original:**
No testing mentioned. Production systems need automated tests.

**Added:**
- Unit test requirements (Jest, 80% coverage)
- Integration test specifications
- E2E test scenarios (Playwright)
- Test data fixtures

**Impact:**
Prevents regressions, enables confident deployments.

---

### 2.4 Observability

**Gap in Original:**
No way to debug issues or monitor health.

**Added:**
- Health endpoints (basic + detailed)
- Structured logging strategy
- Debug mode for troubleshooting
- Request ID tracking

**Impact:**
When something breaks, you can figure out why.

---

### 2.5 PC Agent Security Hardening

**Gap in Original:**
PC Agent mentioned but security boundaries unclear.

**Added:**
- Capability levels (0-3)
- Directory restrictions with allowlist
- Script allowlist with content hashing
- Browser automation domain restrictions
- Dangerous operation blocklist

**Impact:**
Prevents accidental or malicious system damage.

---

### 2.6 Accessibility Requirements

**Gap in Original:**
ADHD-first design mentioned but no accessibility specs.

**Added:**
- WCAG 2.1 AA compliance targets
- ADHD-specific accommodations
- Voice accessibility options
- Cognitive load reduction patterns

**Impact:**
Atlas actually works for its intended user.

---

## Part 3: Refinements & Polish

### 3.1 Persona Specification Enhanced

**Original:**
Good concept but vague on implementation.

**Improved:**
- Explicit response templates
- Forbidden phrases list
- Voice command registry
- Character limits for responses

**Before:**
> "Default style: concise, action-first, zero shame"

**After:**
```markdown
### Response Templates
Status check:
"[Current focus]. Next: [action]. [Optional: time estimate]"
Example: "Writing the quarterly report. Next: finish executive summary. About 20 minutes."

### Forbidden Phrases
- "I understand this must be frustrating"
- "Have you considered..."
- Anything over 15 words for routine responses
```

---

### 3.2 Focus Sprint System Enhanced

**Original:**
Basic sprint concept mentioned.

**Improved:**
- Four sprint types with use cases
- Complete flow (start → during → end)
- Smart defaults based on learning
- Integration with drift detection

---

### 3.3 Memory System Clarified

**Original:**
Three tiers mentioned but rules unclear.

**Improved:**
- Explicit retention policies
- Size limits per tier
- Promotion/demotion rules
- Privacy controls

---

## Part 4: Structural Improvements

### 4.1 Information Architecture

**Original Issues:**
- Requirements scattered across sections
- Duplicate information
- Inconsistent formatting
- No clear priority hierarchy

**Improvements:**
- Logical section ordering (critical first)
- Consolidated related requirements
- Consistent heading levels
- Visual hierarchy with icons

### 4.2 Actionability

**Original Issues:**
- Some requirements too vague
- Missing acceptance criteria
- No verification method

**Improvements:**
- Specific, measurable requirements
- Clear acceptance checklist
- Testable criteria

### 4.3 Completeness

**Added Sections:**
- Implementation phases
- Deployment instructions
- Environment variables
- Development setup

---

## Part 5: What I Didn't Change (And Why)

### 5.1 ADHD Context Section
Your personal context is excellent. It sets the right emotional tone and ensures Claude Code understands the stakes. I only added formatting polish.

### 5.2 Phrase Bank
Your phrases are perfect. They're natural, kind, and ADHD-appropriate. I organized them better but kept your language.

### 5.3 Core Persona
Atlas's identity is well-defined. I added implementation details but kept your vision intact.

### 5.4 Safe Update Model
Your "no silent writes" principle is crucial. I added technical implementation but kept your philosophy.

---

## Part 6: Usage Recommendations

### How to Use the Revised Prompt

1. **Start Fresh**: Begin a new Claude Code session
2. **Paste Full Prompt**: Include everything, don't truncate
3. **Specify Phase**: "Let's start Phase 1: Foundation"
4. **Track Progress**: Check TODO LIST.md after each session
5. **Carry Forward**: At session end, save the resume instructions

### Expected Session Count
- Minimum viable Atlas: 4-6 sessions
- Full feature set: 8-10 sessions
- Production-ready with testing: 12-15 sessions

### Quality Checkpoints
After each phase:
- [ ] All files compile/run
- [ ] TODO LIST.md updated
- [ ] No "TODO" comments in code
- [ ] Health endpoint returns 200

---

## Part 7: Future Enhancement Suggestions

### v1.1 Considerations (Not in Current Prompt)
1. **Calendar Integration**: Google/Apple Calendar sync
2. **Email Triage**: Gmail/Outlook integration
3. **Mobile Notifications**: Push notification support
4. **Voice Wake Word**: "Hey Atlas" hands-free activation
5. **Multi-User**: Family/team support
6. **Plugins**: Extensibility framework

### Security Enhancements
1. **End-to-End Encryption**: Encrypt context at rest
2. **Hardware Key Support**: YubiKey for high-risk actions
3. **Audit Log Signing**: Tamper-proof logs

### Scalability
1. **Cloud Deployment Option**: Not just local
2. **Sync Service**: Multi-device real-time sync
3. **Backup Service**: Automated cloud backup

---

## Conclusion

Your original prompt showed deep understanding of user needs and emotional design—rare qualities. The revised prompt maintains your vision while adding the technical rigor needed for production software.

The result is a specification that Claude Code can follow to build a system worthy of daily reliance.

**Key Takeaway**: You've designed Atlas with your heart (ADHD-first, emotionally aware, trustworthy). The revisions add the engineering discipline to make that vision real.

---

## Files Provided

1. **atlas-prompt-v2.md** - Complete revised prompt, ready to use
2. **analysis-report.md** - This document

Both files are ready for download.