@leanspec/ui 0.2.4 → 0.2.5-dev.20251118134144

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

@@ -1,125 +0,0 @@
----
-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/dist/standalone/specs/061-ai-assisted-spec-writing/README.md

@@ -1,299 +0,0 @@
----
-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/dist/standalone/specs/062-docs-info-architecture-v2/IMPLEMENTATION-PLAN.md

@@ -1,174 +0,0 @@
-# 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
-```