@leanspec/ui 0.2.7-dev.20251126100750 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/060-core-concepts-coherence/README.md

@@ -0,0 +1,125 @@
+---
+status: complete
+created: '2025-11-07'
+tags:
+  - docs
+  - ux
+  - information-architecture
+priority: high
+created_at: '2025-11-07T12:20:31.352Z'
+updated_at: '2025-11-07T12:25:39.409Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-07T12:21:12.082Z'
+  - status: complete
+    at: '2025-11-07T12:25:39.409Z'
+completed_at: '2025-11-07T12:25:39.409Z'
+completed: '2025-11-07'
+---
+
+# Core Concepts Documentation Coherence
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-07 · **Tags**: docs, ux, information-architecture
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Align Core Concepts around an AI-era model that treats specs as executable blueprints for autonomous agents. This spec reframes the docs into a layered structure (Constraints → First Principles → Patterns) and maps them cleanly to three pages: Understanding LeanSpec, The 12 Patterns for AI‑Executable Specs, and When to Use.
+
+## Problem
+
+The Core Concepts documentation pages (First Principles, Philosophy, Agile Principles, When to Use) feel isolated and incoherent:
+
+1. **Circular Navigation**: Each page tells readers to start somewhere else, creating confusion about entry point
+2. **Overlapping Content**: Same concepts (Context Economy, signal-to-noise, etc.) explained differently across pages without clear differentiation
+3. **Inconsistent Depth**: First Principles is very detailed, Philosophy is abstract, Agile Principles is practical—no clear progression
+4. **Missing Narrative**: No story arc showing how concepts build on each other
+5. **Academic Taxonomy**: "First Principles" vs "Philosophy" vs "Agile Principles" distinction is unclear to readers
+
+**Result**: Readers must mentally stitch together ideas across pages, creating cognitive overhead.
+
+## The Real Innovation
+
+Traditional specs assume a human-only loop: human writes → human reads → human implements. LeanSpec assumes an AI-first loop: human writes → AI reads → AI implements → human reviews. That shift changes what “good” looks like: specs must be simultaneously human-readable and machine-executable within finite context windows and real token costs.
+
+## Solution
+
+Restructure Core Concepts around a layered model tailored to AI-executable specs, then map that model to three concise pages:
+
+### Layered Model
+- **Layer 1 — Constraints (discovered, not chosen)**: Physics (finite context windows), Biology (working memory ~7 items), Economics (tokens/time cost money)
+- **Layer 2 — First Principles (derived from constraints)**: The existing 5 principles are the core innovation and remain authoritative
+- **Layer 3 — Practices (applied patterns for execution)**: Replace generic “writing specs” advice with concrete, repeatable patterns that make specs AI-executable
+
+### Page 1: Understanding LeanSpec (Constraints + First Principles + Mindset)
+**Goal**: Foundation and rationale in one place  
+**Flow**: Constraints → First Principles → Mindset → Success Criteria
+
+### Page 2: The 12 Patterns for AI‑Executable Specs (NEW)
+**Goal**: Practical, concrete techniques that make specs executable by agents  
+**The 12 Patterns**:
+1. Structure as signal — use consistent sections (Problem/Solution/Success)
+2. Examples over abstraction — show API calls and payloads
+3. Explicit boundaries — state what’s out of scope
+4. Success criteria first — define “done” upfront
+5. Intent over steps — explain why, not how
+6. Parseable metadata — use frontmatter for machine reading
+7. Natural language body — write for human understanding
+8. Concrete over theoretical — prefer real examples
+9. Constraints as guardrails — make limits explicit
+10. Iteration markers — mark TBDs and proceed
+11. Learning capture — update spec from implementation
+12. Single source of truth — spec reflects current reality
+
+### Page 3: When to Use (integrated, unchanged in scope)
+**Goal**: Decision framework for applying LeanSpec  
+Add clear references back to Understanding and Patterns; emphasize judgment over rules.
+
+## Design
+
+The design is intentionally minimal to reduce cognitive and token load:
+- Use a three-layer model: Constraints (immutable) → First Principles (derived) → Patterns (applied)
+- Map layers to three pages to establish a clear 1→2→3 learning path
+- Replace generic advice with 12 concrete patterns optimized for AI execution
+- Keep cross-links directional (Understanding → Patterns → When to Use) to avoid circular navigation
+
+## Implementation Plan
+
+### Phase 1: Understanding LeanSpec (Merge + Reframe)
+- [ ] Merge first-principles.mdx + philosophy.mdx
+- [ ] Frame with Constraints → First Principles → Mindset
+- [ ] Remove circular “start here” references
+- [ ] Add concise success criteria section
+
+### Phase 2: 12 Patterns (Create New Page)
+- [ ] Create 12-patterns.mdx (AI-executable patterns)
+- [ ] Port practical guidance from “writing specs” into patterns
+- [ ] Add examples for at least patterns 1–6
+- [ ] Cross-link each pattern to relevant principle(s)
+
+### Phase 3: Navigation & Cross-links
+- [ ] Update `docs-site/sidebars.ts` to order: Understanding → 12 Patterns → When to Use
+- [ ] Update cross-references between pages
+- [ ] Remove “start with X then come back” phrasing
+
+### Phase 4: Clean Up & Redirects
+- [ ] Remove/retire `philosophy.mdx` and `first-principles.mdx` in favor of Understanding
+- [ ] Deprecate/replace “writing-specs” with `12-patterns.mdx`
+- [ ] Update any internal/external links and redirects
+
+## Success Criteria
+
+- [ ] No circular “start here” references
+- [ ] Clear 1→2→3 progression (Understanding → 12 Patterns → When to Use)
+- [ ] Patterns map to principles; each pattern has at least one example
+- [ ] Readers can apply patterns without jumping pages
+- [ ] Docs site builds successfully and all internal links work
+
+## Trade-offs
+
+**Lose**: Familiar “agile-style” practices page  
+**Gain**: AI-era specificity with patterns that are immediately executable by agents
+
+**Rationale**: LeanSpec optimizes for Context Economy and AI execution. Layered structure (Constraints → Principles → Patterns) reduces cognitive load and increases machine actionability.

package/.next/standalone/packages/ui/dist/standalone/specs/061-ai-assisted-spec-writing/README.md

@@ -0,0 +1,299 @@
+---
+status: complete
+created: '2025-11-07'
+tags:
+  - ai
+  - philosophy
+  - docs
+priority: high
+created_at: '2025-11-07T15:44:34.381Z'
+updated_at: '2025-11-10T07:22:30.312Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-07T15:51:24.539Z'
+  - status: complete
+    at: '2025-11-10T07:22:30.312Z'
+completed_at: '2025-11-10T07:22:30.312Z'
+completed: '2025-11-10'
+related: [43]
+---
+
+# AI-Assisted Spec Writing
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-07 · **Tags**: ai, philosophy, docs
+
+**Project**: lean-spec  
+**Team**: Core Development  
+**Related**: [043-official-launch-02](../043-official-launch-02/) - Blocks v0.2.0 launch
+
+**⚠️ CRITICAL FOR 0.2.0 LAUNCH** - Must resolve before finalizing positioning and "When to Use" docs.
+
+## Overview
+
+**Current State:**
+LeanSpec assumes: Human writes spec → AI implements from spec
+- Docs focus on "making specs AI-readable/executable"
+- Decision criteria: "Will AI need this context to execute?"
+- Value prop: Specs bridge human intent to machine execution
+
+**The Question:**
+If AI assists in **writing specs** (not just implementing), does this change our docs?
+
+**The Shift:**
+Human provides intent → AI drafts spec → Human refines → AI implements
+- Specs become **refinement artifacts** in human-AI conversation
+- Decision shifts: "Should I formalize intent as spec, or just converse with AI?"
+- New question: **When does structuring intent into a spec add value over direct conversation?**
+
+**Impact:**
+This fundamentally changes:
+1. Value proposition of specs
+2. Decision criteria for "when to use"
+3. How we frame the methodology
+4. What makes a "good spec"
+
+## Key Questions
+
+### 1. Does This Change "When to Use"?
+
+**Current logic:**
+- Write spec when AI needs context to implement
+- Skip when intent is self-evident
+
+**New logic (if AI writes specs):**
+- Write spec when formalization adds value over conversation
+- Skip when conversational iteration is faster
+- But... what adds value? When is structure better than chat?
+
+**✅ ANSWER:**
+The core value proposition doesn't change—**specs add value when persistence and structure matter**. However, the decision criteria expand:
+
+**Write a spec when (EXPANDED):**
+- ✅ Intent needs to persist (reference, onboarding, decisions)
+- ✅ Multiple stakeholders need alignment (can't all chat with AI)
+- ✅ Compliance/audit trail required
+- ✅ Complex enough that conversation would drift
+- ✅ **NEW:** Conversation has clarified intent enough to formalize
+- ✅ **NEW:** Multiple iterations with AI have refined the approach
+
+**Skip the spec when:**
+- ❌ Quick feature, no ambiguity (AI can draft + implement directly)
+- ❌ Exploratory work (conversation is better for discovery)
+- ❌ **NEW:** Still discovering what to build (keep conversing)
+
+**Key Insight:** AI-assisted authoring makes specs MORE accessible (easier to create), but doesn't change WHEN they're needed. The decision point is still: **"Does formalization add value?"**
+
+### 2. Does This Change First Principles?
+
+**✅ ANSWER:** First principles remain valid, but their application evolves:
+
+**Context Economy** - **Still critical.** AI can help keep specs concise by drafting minimal versions. But AI can also be verbose—human review ensures economy.
+
+**Signal-to-Noise** - **Still critical.** AI might expand prompts verbosely. Human refinement cuts noise. The test remains: "What decision does this inform?"
+
+**Intent Over Implementation** - **EVEN MORE critical.** When AI drafts specs AND implements, capturing "why" is essential. AI needs intent to make good decisions at both stages.
+
+**Bridge the Gap** - **Evolution, not change.** Specs still bridge human intent to machine execution. But now the bridge is co-created: Human intent → AI draft spec → Human refine → AI implement.
+
+**Progressive Disclosure** - **AI can accelerate this.** AI can draft minimal specs, then expand specific sections on request. Human decides what complexity to add.
+
+**Conclusion:** First principles are reinforced, not replaced. AI-assisted authoring makes them MORE important because AI can violate them (verbosity, implementation focus) without human guidance.
+
+### 3. Does This Change Success Criteria?
+
+**Current:** Good spec = AI can implement correctly
+**New:** Good spec = AI can draft it + AI can implement from it + Humans understand it
+
+**✅ ANSWER:** Success criteria expand, but don't fundamentally change:
+
+**A good spec must:**
+1. **Fit in working memory** (Context Economy)
+2. **Inform decisions** (Signal-to-Noise)
+3. **Capture intent** (Intent Over Implementation)
+4. **Bridge human-AI understanding** (Bridge the Gap)
+5. **Grow naturally** (Progressive Disclosure)
+6. **Be maintainable** by humans AND AI
+7. **Support both authoring and implementation** workflows
+
+**This IS a higher bar**, but it's achievable because:
+- AI handles first drafts (reduces authoring burden)
+- Humans refine for clarity (ensures quality)
+- LeanSpec principles guide both (maintain standards)
+
+### 4. What's the New Mental Model?
+
+**✅ ANSWER:** All three models are valid, depending on context. We adopt **Spec-as-Checkpoint** as the primary mental model, with the others as variations:
+
+**Primary: Spec-as-Checkpoint** (Most Common)
+- Conversation with AI → Crystallize into spec → Continue from spec
+- Spec = formalized agreement/checkpoint in ongoing work
+- **Use when:** Intent has been clarified through conversation and needs to be captured before implementation
+
+**Variation 1: Spec-as-Artifact** (Formal Projects)
+- Spec = durable output of human-AI collaboration
+- Can be referenced, shared, evolved over time
+- **Use when:** Work needs documentation for compliance, onboarding, or long-term reference
+
+**Variation 2: Spec-as-Context** (Living Documentation)
+- Spec = structured context for AI + humans
+- Still bridges intent to execution, but co-created
+- **Use when:** Spec evolves alongside implementation (SDD-style iterative refinement)
+
+**Key Insight:** These are phases, not separate approaches. Most specs start as checkpoints, evolve as context, and end as artifacts.
+
+## Design
+
+### Proposed Changes to Docs
+
+#### 1. Update "When to Use" (docs-site/docs/guide/when-to-use.mdx)
+
+**Add section: "When AI Assists in Writing Specs"**
+
+Current decision: "Will AI need this context to execute?"
+New decision: "When does formalizing intent as a spec add value?"
+
+**Write a spec when:**
+- Intent needs to persist (decisions, reference, onboarding)
+- Multiple stakeholders need shared understanding
+- Work is complex enough that conversation would drift
+- Audit trail or compliance required
+- Progressive refinement benefits from structure
+
+**Skip the spec when:**
+- Quick feature with no ambiguity (AI can draft + implement directly)
+- Exploratory work (conversation is better for discovery)
+- One-off prototype or experiment
+- Context is already clear in codebase
+
+#### 2. Update "Understanding LeanSpec" (docs-site/docs/guide/understanding.mdx)
+
+**Add mental model for AI-assisted spec writing**
+
+Clarify that specs can be:
+- Human-written, AI-implemented (traditional)
+- AI-drafted, human-refined, AI-implemented (assisted)
+- Co-created iteratively (collaborative)
+
+All three modes are valid. First principles still apply.
+
+#### 3. Update "AI Integration" docs (docs-site/docs/guide/ai/index.mdx)
+
+**Expand to include AI-assisted spec authoring**
+
+Current: Focus on AI implementing from specs
+Add: AI drafting specs from human intent
+
+Workflow becomes:
+1. Human articulates intent (conversation, notes, rough outline)
+2. AI drafts initial spec following LeanSpec principles
+3. Human reviews, refines, adds context
+4. Spec serves as checkpoint/contract
+5. AI implements from refined spec
+
+#### 4. Consider New Page: "Writing Specs with AI"
+
+**Topics:**
+- How to prompt AI to draft specs
+- What to review/refine in AI-drafted specs
+- Common pitfalls (AI verbosity, missing context)
+- Ensuring first principles are maintained
+- When to iterate vs. accept draft
+
+### Technical Considerations
+
+**No tooling changes needed** - This is purely docs/methodology
+
+**But future opportunities:**
+- `lean-spec draft "feature description"` - AI drafts spec from prompt
+- `lean-spec refine <spec>` - AI suggests improvements
+- `lean-spec validate <spec> --ai-check` - AI validates against first principles
+
+## Plan
+
+### Phase 1: Research & Define (This Spec)
+- [x] Identify the question
+- [x] Answer key questions (above)
+- [x] Define new mental model (Spec-as-Checkpoint primary, with variations)
+- [ ] Validate with team/community (deferred to post-implementation feedback)
+
+### Phase 2: Update Core Docs
+- [x] Update "When to Use" with AI-assisted context (merged into understanding.mdx)
+- [x] Update "Understanding LeanSpec" with new mental models (decision framework added)
+- [x] Update "AI Integration" docs with authoring workflow (covered in writing-specs-with-ai.mdx)
+- [x] Review all docs for consistency (validated via build + validate)
+
+### Phase 3: New Content (If Needed)
+- [x] Created dedicated "Writing Specs with AI" page (docs-site/docs/guide/usage/ai-assisted/writing-specs-with-ai.mdx)
+- [x] Added examples of AI-drafted specs and workflows
+- [x] Documented best practices for prompting (Do's and Don'ts)
+- [x] Created workflow templates (5-step process, common patterns)
+
+### Phase 4: Validation
+- [ ] Dogfood: Use AI to draft/refine specs
+- [ ] Get feedback from community
+- [ ] Iterate based on real usage
+
+## Test
+
+**Validation Criteria (Phases 1-3):**
+
+- [x] Docs clearly explain when to formalize intent as spec vs. just converse with AI (understanding.mdx updated with decision framework)
+- [x] First principles still make sense in AI-assisted context (understanding.mdx confirms they're reinforced, not replaced)
+- [x] New mental models are clear and actionable (Spec-as-Checkpoint, Artifact, Context defined in writing-specs-with-ai.mdx)
+- [x] No contradictions between old/new framing (consistent messaging across all updated docs)
+- [x] Examples demonstrate AI-assisted workflow (writing-specs-with-ai.mdx has 5-step workflow + patterns)
+- [ ] Community understands and can apply guidance (deferred to Phase 4: user feedback)
+
+**Additional Validation:**
+- [x] Docs build successfully (verified with `npm run build`)
+- [x] Spec structure validated (no new errors from our changes)
+- [x] All three target docs updated (understanding.mdx updated; when-to-use.mdx was merged into understanding.mdx by spec 062)
+- [x] New dedicated page created (guide/usage/ai-assisted/writing-specs-with-ai.mdx)
+- [x] Sidebar navigation updated (added to "AI-Assisted Workflows" section)
+
+**Success Signals (To be measured in Phase 4):**
+- Users know when to use specs vs. conversation
+- AI-drafted specs follow LeanSpec principles
+- Methodology remains coherent and practical
+- No confusion about "what LeanSpec is for"
+
+## Notes
+
+### Core Insight
+
+The fundamental value of specs doesn't change:
+- **Persistence** - Specs outlive conversations
+- **Shared understanding** - Specs align stakeholders
+- **Structure** - Specs prevent drift and ambiguity
+- **Context** - Specs bridge intent to execution
+
+What changes is **how specs are created**, not **why they exist**.
+
+### Open Questions
+
+1. **Does AI-assisted writing make specs MORE or LESS necessary?**
+   - Less: AI can implement from conversation
+   - More: Specs formalize and checkpoint the conversation
+
+2. **When is conversation better than specs?**
+   - Rapid exploration, high uncertainty
+   - Simple features, no ambiguity
+   - One-off work, no future reference needed
+
+3. **How do we teach "when to formalize"?**
+   - This is judgment, not rules
+   - Need examples and heuristics
+   - Maybe: "If conversation > 5 turns, consider formalizing"
+
+### Related Work
+
+- **[049-leanspec-first-principles](../049-leanspec-first-principles/)** - First principles still apply
+- **[043-official-launch-02](../043-official-launch-02/)** - Original positioning
+- **AI Integration docs** - Current state of AI guidance
+
+### Next Steps
+
+1. **Discuss with community** - Is this the right framing?
+2. **Prototype workflows** - Try AI-assisted spec writing
+3. **Draft doc updates** - Apply learnings
+4. **Validate with real usage** - Does it work in practice?

package/.next/standalone/packages/ui/dist/standalone/specs/062-docs-info-architecture-v2/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,174 @@
+# Implementation Plan
+
+This document outlines the 11-phase plan to restructure the documentation site.
+
+## Phase 1: Core Concepts Restructure (WHY)
+
+- [ ] Restructure `guide/understanding.mdx` (KEEP as entry point)
+  - [ ] Merge positioning + "When to Use" content from `when-to-use.mdx`
+  - [ ] Add problem/solution overview
+  - [ ] Add decision framework
+  - [ ] Add Core Concepts overview with links
+- [ ] Extract `guide/first-principles.mdx` from understanding.mdx
+  - [ ] Keep constraints and 5 principles sections
+  - [ ] Remove mindset/beliefs content (move to philosophy)
+  - [ ] Keep conflict resolution examples
+- [ ] Create `guide/context-engineering.mdx` (NEW)
+  - [ ] Reference spec 059 CONTEXT-ENGINEERING.md
+  - [ ] Explain 4 strategies and 4 failure modes
+  - [ ] Show how LeanSpec applies context engineering
+  - [ ] Link to First Principles (Context Economy)
+- [ ] Create `guide/ai-agent-memory.mdx` (NEW)
+  - [ ] Explain specs as persistent memory layer
+  - [ ] Reference LangChain article on agent memory
+  - [ ] Connect to semantic memory concept
+  - [ ] Show MCP integration for memory retrieval
+- [ ] Update `guide/philosophy.mdx`
+  - [ ] Extract mindset/beliefs from old understanding.mdx
+  - [ ] Add links to First Principles, Context Engineering, AI Agent Memory
+  - [ ] Integrate memory concept into mental models
+  - [ ] Structure: Beliefs → Mental Models → Mindset
+
+## Phase 2: Remove "Working with AI" Section
+
+- [ ] Merge AI setup into Getting Started
+  - [ ] Update `guide/getting-started.mdx` with MCP setup
+  - [ ] Add AGENTS.md reference
+  - [ ] Keep setup concise
+- [ ] Migrate AI best practices content
+  - [ ] Will move to new `usage/ai-assisted/` section in Phase 4
+- [ ] Delete `guide/ai/` directory after migration complete
+
+## Phase 3: Create Usage Section Structure
+
+- [ ] Create `guide/usage/` directory structure
+  - [ ] `basic-commands/`
+  - [ ] `project-management/`
+  - [ ] `advanced-features/`
+  - [ ] `ai-assisted/`
+
+## Phase 4: Essential Usage (New Content)
+
+- [ ] Create `guide/usage/essential-usage/creating-managing.mdx`
+  - [ ] Document create, update, archive commands
+  - [ ] Include examples and common workflows
+  - [ ] Add cross-links to CLI Reference
+- [ ] Create `guide/usage/essential-usage/finding-specs.mdx`
+  - [ ] Document list, search, view commands
+  - [ ] Show filtering and querying examples
+  - [ ] Add cross-links to CLI Reference
+- [ ] Create `guide/usage/essential-usage/spec-structure.mdx`
+  - [ ] Explain frontmatter fields
+  - [ ] Document content section conventions
+  - [ ] Metadata management best practices
+  - [ ] Add cross-links to Frontmatter Reference and Config Reference
+
+## Phase 5: Project Management (Rename Workflow)
+
+- [ ] Move `guide/board-stats.mdx` → `guide/usage/project-management/board-stats.mdx`
+- [ ] Move `guide/dependencies.mdx` → `guide/usage/project-management/dependencies.mdx`
+- [ ] Move `guide/validation.mdx` → `guide/usage/project-management/validation.mdx`
+- [ ] Add index page `guide/usage/project-management/index.mdx`
+
+## Phase 6: Advanced Features (Rename Features)
+
+- [ ] Move `guide/templates.mdx` → `guide/usage/advanced-features/templates.mdx`
+- [ ] Move `guide/custom-fields.mdx` → `guide/usage/advanced-features/custom-fields.mdx`
+- [ ] Move `guide/variables.mdx` → `guide/usage/advanced-features/variables.mdx`
+- [ ] Move `guide/frontmatter.mdx` → `guide/usage/advanced-features/frontmatter.mdx`
+- [ ] Add sub-specs documentation (if not exists)
+
+## Phase 7: AI-Assisted Writing
+
+- [ ] Move `guide/ai-executable-patterns.mdx` → `guide/usage/ai-assisted/ai-executable-patterns.mdx`
+- [ ] Create `guide/usage/ai-assisted/mcp-integration.mdx`
+  - [ ] MCP server setup (migrate from guide/ai/setup.mdx)
+  - [ ] Usage examples
+  - [ ] Troubleshooting
+- [ ] Create `guide/usage/ai-assisted/agent-configuration.mdx`
+  - [ ] AGENTS.md explanation
+  - [ ] Configuration examples
+  - [ ] Best practices (migrate from guide/ai/best-practices.mdx)
+
+## Phase 8: Update Navigation (sidebars.ts)
+
+- [ ] Update `docs-site/sidebars.ts`
+  - [ ] Restructure Core Concepts section
+  - [ ] Remove "Working with AI" section
+  - [ ] Remove "Features" and "Workflow" sections
+  - [ ] Add new "Usage" section with 4 subcategories
+  - [ ] Update all item paths
+
+## Phase 9: Update Cross-References
+
+- [ ] Update all internal links in documentation
+  - [ ] Fix links to moved pages
+  - [ ] Update "Working with AI" references
+  - [ ] Update "Features" and "Workflow" references
+- [ ] Update Getting Started links
+- [ ] Update Overview page links
+
+## Phase 10: Cleanup
+
+- [ ] Delete old files
+  - [ ] `guide/when-to-use.mdx` (content merged into understanding.mdx)
+  - [ ] `guide/ai/` directory (all content migrated)
+- [ ] Delete empty directories
+- [ ] Remove old sections from sidebars.ts
+
+## Phase 11: Testing & Validation
+
+- [ ] Build docs-site: `cd docs-site && npm run build`
+- [ ] Verify no broken links
+- [ ] Check navigation flow
+- [ ] Test all cross-references
+- [ ] Validate search functionality
+- [ ] Review on mobile/desktop
+
+## Estimated Effort
+
+- **Phase 1-2 (Core Concepts + new pages)**: 4-5 hours
+- **Phase 3-7 (Usage)**: 5-6 hours
+- **Phase 8-11 (Navigation + Testing)**: 2-3 hours
+- **Total**: 11-14 hours over 2-3 days
+
+## Content Migration Map
+
+```
+OLD LOCATION                          → NEW LOCATION
+================================================================
+guide/understanding.mdx               → Split & Restructure:
+  - Positioning + Problem/Solution    → guide/understanding.mdx (keep, restructure)
+  - Constraints + 5 Principles        → guide/first-principles.mdx (extract)
+  - Mindset + Beliefs                 → guide/philosophy.mdx (extract)
+
+guide/when-to-use.mdx                 → guide/understanding.mdx (merge into)
+
+(NEW - from spec 059)                 → guide/context-engineering.mdx
+(NEW - from research)                 → guide/ai-agent-memory.mdx
+
+guide/ai-executable-patterns.mdx      → guide/usage/ai-assisted/ai-executable-patterns.mdx
+
+guide/ai/setup.mdx                    → Split:
+  - Setup basics                      → guide/getting-started.mdx (merged)
+  - MCP details                       → guide/usage/ai-assisted/mcp-integration.mdx
+
+guide/ai/best-practices.mdx           → guide/usage/ai-assisted/agent-configuration.mdx (merged)
+
+guide/ai/agents-md.mdx                → guide/usage/ai-assisted/agent-configuration.mdx (merged)
+
+guide/ai/examples.mdx                 → Distribute to relevant sections
+
+guide/templates.mdx                   → guide/usage/advanced-features/templates.mdx
+guide/custom-fields.mdx               → guide/usage/advanced-features/custom-fields.mdx
+guide/variables.mdx                   → guide/usage/advanced-features/variables.mdx
+guide/frontmatter.mdx                 → guide/usage/advanced-features/frontmatter.mdx
+
+guide/board-stats.mdx                 → guide/usage/project-management/board-stats.mdx
+guide/dependencies.mdx                → guide/usage/project-management/dependencies.mdx
+guide/validation.mdx                  → guide/usage/project-management/validation.mdx
+
+(NEW)                                 → guide/usage/essential-usage/creating-managing.mdx
+(NEW)                                 → guide/usage/essential-usage/finding-specs.mdx
+(NEW)                                 → guide/usage/essential-usage/spec-structure.mdx
+```