.agents/memory/2026-02-27-onboarding-overhaul-implementation-planning.md

2026-02-27 Session Notes

Onboarding Overhaul Implementation Planning

Nicholai began session to implement the onboarding overhaul (roadmap sections 2.1-2.4), the next priority tier after completing four "on fire" items (defaults, npm gate, hook isolation, non-interactive CLI).

Problem Context

The current /onboarding skill works but suffers from structural issues: no step indicators, no upfront outline, redundant timezone questions, and misleading guidance about manual memory workflows. The remember and recall skills encourage users to manually capture memories, which duplicates the automatic pipeline and distorts importance scoring.

Implementation Plan

Five files require modification:

1. SKILL.md (onboarding) — Major structural rewrite with new sections:

   • Expanded frontmatter describing scope (what it does/doesn't do)
   • "What This Skill Does" transparency section
   • "Guiding Voice" tone guide (warm, patient, refined; emphasizes "we" language; avoids roleplay to prevent prompt injection warnings)
   • "Starting the Interview" section with full 6-step outline before questions
   • Step indicators at each phase transition
   • Relaxation cues at phase ends ("we can revisit anytime")
   • Removed timezone question from Phase 3
   • Updated Quick Mode to write "one rule your agent should always follow" instead of memory entries

2. Remember skill — Set user_invocable: false to hide from users and prevent hook-based auto-remembering that doubles token usage

3. Recall skill — Add disclaimer section explaining automatic injection at session start and when manual recall is appropriate (targeted searches, old decisions, debugging)

4. USER.md.template — Remove timezone from line 13

5. AGENTS.md.template — Remove timezone from line 60

Key Design Decisions

• Persona guidance framed as tone guidance ("adopt a warm tone") rather than character roleplay to avoid triggering host agent safety heuristics
• "Black wall gateway" aesthetic conveyed through quiet confidence rather than cyberpunk keywords
• Transparency declarations satisfy safety requirements without separate "trust me" blocks
• Remember skill fully hidden; recall remains user-accessible since it's read-only and useful for debugging

Verification Strategy

After implementation: build packages, verify skill sync, test all three skills in Claude Code, confirm timezone removed from interview flow and templates.