Initial commit

2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
--- a/skills/ln-210-epic-coordinator/SKILL.md
+++ b/skills/ln-210-epic-coordinator/SKILL.md
@@ -0,0 +1,594 @@
+---
+name: ln-210-epic-coordinator
+description: CREATE/REPLAN Epics from scope (3-7 Epics). Batch Preview + Auto-extraction. Decompose-First Pattern. Auto-discovers team ID.
+---
+
+# Epic Coordinator
+
+Universal Epic management coordinator that handles both creation and replanning through scope decomposition.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Start new scope/initiative requiring decomposition into multiple logical domains (CREATE mode)
+- Break down large architectural requirement into Epics
+- Update existing Epics when scope/requirements change (REPLAN mode)
+- Rebalance Epic scopes within an initiative
+- Add new Epics to existing initiative structure
+- First step in project planning (scope → Epics → Stories → Tasks)
+- Define clear scope boundaries and success criteria for each domain
+
+**Output:** 3-7 Linear Projects (logical domains/modules)
+
+## Core Concepts
+
+### Decompose-First Pattern
+
+**Key principle:** ALWAYS analyze scope and build IDEAL Epic plan FIRST, THEN check existing Epics to determine mode:
+- **No existing Epics** → CREATE MODE (generate and create all Epics)
+- **Has existing Epics** → REPLAN MODE (compare, determine operations: KEEP/UPDATE/OBSOLETE/CREATE)
+
+**Rationale:** Ensures consistent Epic decomposition based on current scope requirements, independent of existing Epic structure (which may be outdated or suboptimal).
+
+### Epic 0 Reserved for Infrastructure
+
+**Rule:** Epic 0 is a reserved index for Infrastructure Epic within an initiative.
+
+**When to use Epic 0:**
+- New project requiring infrastructure setup
+- Multi-stack project (Frontend + Backend on different stacks)
+- Project with security/monitoring/deployment requirements
+
+**Epic indexes within initiative:**
+- **Epic 0:** Infrastructure & Operations (if needed)
+- **Epic 1, 2, 3, ... N:** Business domains
+
+**Linear Project Titles:**
+- Use Next Epic Number from kanban_board.md for sequential numbering
+- Example: Next Epic Number = 11
+  - Epic 0 → Linear title: "Epic 11: Infrastructure & Operations"
+  - Epic 1 → Linear title: "Epic 12: User Management"
+  - Epic 2 → Linear title: "Epic 13: Product Catalog"
+
+**Important:** Epic 0/1/2 are initiative-internal indexes for organizing domains. Linear uses global Next Epic Number for project titles.
+
+---
+
+## Workflow
+
+### Phase 1: Discovery & Research
+
+**Objective:** Gather all necessary context before Epic decomposition.
+
+**Step 1: Load Configuration**
+
+Auto-discovers Team ID and Next Epic Number from `docs/tasks/kanban_board.md`:
+- **Team ID:** Reads Linear Configuration table → Fallback: Ask user directly
+- **Next Epic Number:** Reads Next Epic Number field → Fallback: Ask user directly
+
+**Details:** See CLAUDE.md sections "Configuration Auto-Discovery" and "Linear Integration".
+
+**Step 2: Project Research**
+
+**Objective:** Research project documentation AND frontend code to understand context BEFORE asking user questions.
+
+**Process:**
+
+1. **Document Scan:**
+   - Use `Glob` to find: `docs/requirements.md`, `docs/architecture.md`, `docs/tech_stack.md`
+   - Use `Read` to load found documents
+
+2. **Frontend Code Scan (if applicable):**
+   - Use `Glob` to find: `**/*.html`, `src/**/*.html`, `public/**/*.html`, `templates/**/*.html`
+   - Use `Read` to load HTML files
+   - Extract functional domains from:
+     - **Navigation menus:** `<nav>`, `<a href>` links reveal feature areas
+     - **Forms:** Input fields reveal data models (user registration, login, checkout)
+     - **Page titles:** `<h1>`, `<title>` tags reveal feature names
+     - **Route patterns:** URL structures reveal domain boundaries
+
+   **Example HTML extraction:**
+   ```html
+   <nav>
+     <a href="/products">Products</a>
+     <a href="/cart">Shopping Cart</a>
+     <a href="/checkout">Checkout</a>
+   </nav>
+   <!-- Reveals domains: Product Catalog, Shopping Cart, Payment -->
+   ```
+
+3. **Extract key information from docs + HTML:**
+   - **Business objectives:** What is the project trying to achieve? (from requirements.md)
+   - **User personas:** Who will use the system? (from requirements.md)
+   - **Major functional domains:** What are the main modules/areas? (from requirements.md, architecture.md, HTML navigation)
+   - **Technical stack:** What technologies mentioned? (from tech_stack.md, architecture.md, HTML meta/script tags)
+   - **Infrastructure requirements:** Any mention of logging, monitoring, deployment, CI/CD, security, performance optimization?
+
+4. **Combine findings:**
+   - Merge domains from docs + HTML (deduplicate, consolidate similar)
+   - Example: "User Auth" (from docs) + "Login" (from HTML) → "User Management"
+
+**Fallback:** If docs AND HTML missing → Skip to Phase 2, will ask user basic questions
+
+**Step 3: Infrastructure Epic Decision**
+
+**Objective:** Determine if Infrastructure Epic (Epic 0) should be proposed.
+
+**Criteria for Infrastructure Epic:**
+
+✅ **PROPOSE Infrastructure Epic (Epic 0)** if ANY of:
+1. **New project** (no `docs/infrastructure.md` found, no Epic "Infrastructure" in kanban_board.md Epic Story Counters)
+2. **Multi-stack** (requirements.md or tech_stack.md mentions frontend AND backend on different stacks - e.g., React + Python)
+3. **Infrastructure requirements mentioned** in requirements.md, architecture.md:
+   - Logging, Error Handling
+   - Monitoring, Alerting
+   - Hosting, Deployment, CI/CD
+   - Security (authentication, authorization, encryption, secrets management)
+   - Performance optimization (caching, rate limiting, database optimization)
+
+❌ **DO NOT propose** if:
+1. Existing project (found `docs/infrastructure.md`)
+2. Epic Story Counters shows existing Epic with "Infrastructure" in title
+3. User explicitly declined in previous interaction
+
+**Decision:** Store YES/NO decision for use in Phase 2
+
+**Output from Phase 1:**
+- Team ID, Next Epic Number
+- Project context (business goals, domains from docs + HTML, tech stack, infrastructure needs) - if found
+- Infrastructure Epic decision (YES/NO)
+
+---
+
+### Phase 2: Scope Analysis & Epic Planning
+
+**Objective:** Identify logical domains and build Epic structure inline.
+
+**Process:**
+
+**Step 1: Auto-identify Domains**
+
+Use research context from Phase 1 Step 2:
+- If project docs found → Extract domains from requirements.md, architecture.md (module names, feature areas)
+- If HTML found → Extract domains from navigation, forms, page structures
+- Combine and deduplicate domains
+- Example: "User Auth" + "Profile Management" → "User Management"
+
+**Fallback:** If no docs/HTML → Ask user basic questions (scope, objectives, functional areas)
+
+**Step 2: Build Epic List (inline)**
+
+**IF Infrastructure needed (from Phase 1 Step 3):**
+- **Epic 0: Infrastructure & Operations**
+  - Goal: Establish foundational infrastructure, deployment pipeline, operational capabilities
+  - Scope: Logging, error handling, monitoring, CI/CD, security baseline, performance
+  - **Multi-stack projects:** Each Story doubles (Frontend Story + Backend Story for same functionality)
+- **Epic 1-N:** Business domains (from Step 1)
+
+**ELSE:**
+- **Epic 1-N:** Business domains only
+
+**Step 3: Determine Epic Count**
+
+- Infrastructure Epic (if applicable): +1 Epic
+- Simple Initiative (1-3 domains): 3-4 Epics total
+- Medium Initiative (4-6 domains): 5-7 Epics total
+- Complex Initiative (7+ domains): 7-10 Epics total (rare)
+- **Max 10 Epics per Initiative** (enforced)
+
+**Step 4: Show Proposed Epic Structure (USER CONTROL POINT 1)**
+
+Display identified Epics with initiative-internal indexes:
+
+```
+📋 Proposed Epic Structure:
+
+Epic 0: Infrastructure & Operations
+Epic 1: User Management
+Epic 2: Product Catalog
+Epic 3: Shopping Cart
+Epic 4: Payment Processing
+Epic 5: Order Management
+
+Total: 6 Epics
+Type "confirm" to proceed, or modify the list
+```
+
+**Step 5: User Confirmation**
+
+- User types "confirm" → Proceed to Phase 3
+- User modifies → Update domain list, show again
+
+**Output:** Approved Epic list (Epic 0-N or Epic 1-N) ready for next phase
+
+---
+
+### Phase 3: Check Existing Epics
+
+**Objective:** Determine CREATE vs REPLAN mode.
+
+Query kanban_board.md and Linear for existing Epics:
+
+1. **Read Epic Story Counters** table in kanban_board.md
+2. **Count existing Epic rows** (excludes header row)
+
+**Decision Point:**
+- **Count = 0** → No existing Epics → **Proceed to Phase 4+5a (CREATE MODE)**
+- **Count ≥ 1** → Existing Epics found → **Proceed to Phase 5b (REPLAN MODE)**
+
+---
+
+### Phase 4: Epic Preparation (CREATE mode only)
+
+**Trigger:** Phase 3 determined Count = 0 (CREATE MODE)
+
+**Objective:** Prepare all Epic documents before batch preview.
+
+**Step 1: Auto-extract Information for ALL Domains**
+
+For EACH domain (from Phase 2), extract answers to 5 key questions from project documentation:
+
+1. **Q1: Business goal** - Why this Epic/domain matters
+   - **Source:** requirements.md (domain objectives section)
+   - **Extraction:** "The [domain] module aims to..." or "Goal: [objective]"
+   - **Fallback:** architecture.md (module purpose)
+
+2. **Q2: Key features in scope** - 3-5 bullet points of capabilities
+   - **Source:** requirements.md (functional requirements for this domain)
+   - **Extraction:** Bulleted lists under domain heading, feature descriptions
+   - **Fallback:** architecture.md (component responsibilities)
+
+3. **Q3: Out of scope** - Prevent scope creep
+   - **Source:** requirements.md (explicitly excluded features section)
+   - **Extraction:** "Not in scope:", "Future versions:", "Out of scope for [domain]:"
+   - **Fallback:** Infer from requirements.md (features NOT mentioned in domain)
+
+4. **Q4: Success criteria** - Measurable outcomes
+   - **Source:** requirements.md (acceptance criteria, metrics, KPIs for domain)
+   - **Extraction:** Performance targets, user metrics, quality gates
+   - **Fallback:** Generic criteria based on domain type (e.g., "<200ms API response" for backend)
+
+5. **Q5: Known risks** (Optional) - Blockers, dependencies
+   - **Source:** architecture.md (technical constraints, dependencies section)
+   - **Extraction:** "Risks:", "Dependencies:", "Constraints:"
+   - **Fallback:** User input if critical, otherwise leave as "To be determined during Story planning"
+
+**If extraction incomplete:**
+- Show extracted information to user
+- Ask ONCE for ALL missing information across ALL domains (batch question, not per-domain)
+- Example: "For Epic 1 (User Management), I couldn't find success criteria. For Epic 2 (Payment), I couldn't find risks. Please provide..."
+
+**Step 2: Generate ALL Epic Documents**
+
+For EACH domain, generate complete Epic document using epic_template_universal.md:
+
+**Epic indexing:**
+- IF Infrastructure Epic exists (from Phase 1 Step 3) → Epic 0 (Infrastructure), Epic 1-N (business domains)
+- ELSE → Epic 1-N (business domains only)
+
+**Linear Title (will be created in Phase 5a):**
+- Use Next Epic Number from kanban_board.md for sequential numbering
+- Format: "Epic {Next Epic Number}: {Domain Title}"
+- Example: Next = 11 → "Epic 11: Infrastructure & Operations"
+
+**Sections:** Goal, Scope In/Out, Success Criteria, Dependencies, Risks & Mitigations, Architecture Impact, Phases
+
+**Use extracted information** from Step 1 for all sections
+
+**Output:** All Epic documents ready (Epic 0-N), indexed within initiative
+
+---
+
+### Phase 5a: Epic Creation (CREATE mode)
+
+**Trigger:** Phase 4 completed preparation
+
+**Objective:** Show preview, get confirmation, create all Epics in Linear.
+
+**Step 1: Show Batch Preview (USER CONTROL POINT 2)**
+
+Display ALL generated Epics with initiative-internal indexes:
+
+```
+📋 Epic Batch Preview (6 Epics to create)
+
+═══════════════════════════════════════════════
+Epic 0: Infrastructure & Operations
+═══════════════════════════════════════════════
+Goal: Establish foundational infrastructure, deployment pipeline, and operational capabilities to support all business Epics
+
+Scope In:
+- Logging and error handling framework
+- Monitoring and alerting system
+- CI/CD pipeline (GitHub Actions)
+- Security baseline (secrets management, encryption)
+- Performance optimization (caching, rate limiting)
+
+Scope Out:
+- Application-specific business logic
+- User-facing features
+- Domain-specific integrations
+
+Success Criteria:
+- All deployments automated via CI/CD (<10 min deployment time)
+- System uptime ≥99.9%
+- API response time <200ms (p95)
+- Security audit passed
+
+═══════════════════════════════════════════════
+Epic 1: User Management
+═══════════════════════════════════════════════
+Goal: Enable users to register, authenticate, and manage their accounts securely
+
+Scope In:
+- User registration with email verification
+- Login/logout with JWT authentication
+- Password reset flow
+- Profile management
+
+Scope Out:
+- Social login (OAuth) - planned for Epic 5
+- Multi-factor authentication - future version
+- User roles and permissions - part of Epic 3
+
+Success Criteria:
+- User registration <2 seconds
+- Login success rate >98%
+- Password reset completion rate >90%
+
+[... all other Epics ...]
+
+───────────────────────────────────────────────
+Total: 6 Epics (Epic 0: Infrastructure, Epic 1-5: Business domains)
+Type "confirm" to create all Epics in Linear
+```
+
+**Step 2: User Confirmation**
+
+- User types "confirm" → Proceed to Step 3
+- User provides feedback → Adjust documents in Phase 4, regenerate preview, repeat
+
+**Step 3: Create All Epics in Linear**
+
+For EACH Epic (in sequential order for numbering consistency):
+
+1. **Get Next Epic Number:**
+   - Read current Next Epic Number from kanban_board.md
+   - Example: 11
+
+2. **Create Linear Project:**
+   - Title: "Epic {Next Epic Number}: {Domain Title}"
+     - Example: "Epic 11: Infrastructure & Operations" (for Epic 0)
+     - Example: "Epic 12: User Management" (for Epic 1)
+   - Description: Complete Epic markdown (from Phase 4 Step 2)
+   - Team: Team ID from Phase 1
+   - State: "planned"
+
+3. **Update kanban_board.md:**
+   - Increment Next Epic Number by 1 in Linear Configuration table
+   - Add new row to Epic Story Counters: `Epic {N} | - | US001 | - | EPN_01`
+   - Add to "Epics Overview" → Active: `- [Epic {N}: Title](link) - Backlog`
+
+4. **Collect URL**
+
+**Step 4: Display Summary**
+
+```
+✅ Created 6 Epics for initiative
+
+Epics created:
+- Epic 11: Infrastructure & Operations (Epic 0 index) [link]
+- Epic 12: User Management (Epic 1 index) [link]
+- Epic 13: Product Catalog (Epic 2 index) [link]
+- Epic 14: Shopping Cart (Epic 3 index) [link]
+- Epic 15: Payment Processing (Epic 4 index) [link]
+- Epic 16: Order Management (Epic 5 index) [link]
+
+Next Epic Number updated to: 17
+
+Next Steps:
+1. Use ln-220-story-coordinator to create Stories for each Epic (run 6 times)
+2. OR use ln-200-scope-decomposer to automate Epic + Story creation
+```
+
+**Output:** Created Epic URLs + summary
+
+---
+
+### Phase 5b: Replan Mode (Existing Epics Found)
+
+**Trigger:** Phase 3 determined Count ≥ 1 (REPLAN MODE)
+
+**Process:**
+
+1. **Load Existing Epics:**
+   - Read Epic Story Counters table from kanban_board.md
+   - For each Epic row: load Epic from Linear via `get_project(id)`
+   - Load FULL description (Goal, Scope In/Out, Success Criteria, Risks, Phases)
+   - Note Epic status (active/archived)
+   - **Total:** N existing Epics
+
+2. **Compare IDEAL Plan (from Phase 2) vs Existing:**
+   - **Match by goal:** Fuzzy match Epic goals + domain names
+   - **Identify operations needed:**
+     - **KEEP:** Epic in IDEAL + existing, goals unchanged → No action
+     - **UPDATE:** Epic in IDEAL + existing, scope/criteria changed → Update description
+     - **OBSOLETE:** Epic in existing, NOT in IDEAL → Archive (state="archived")
+     - **CREATE:** Epic in IDEAL, NOT in existing → Create new
+
+3. **Categorize Operations:**
+   ```
+   ✅ KEEP (N Epics): No changes needed
+   - Epic 5: User Management
+   - Epic 6: Payment Processing
+
+   🔧 UPDATE (M Epics): Scope or criteria changed
+   - Epic 7: Reporting (Scope modified: add real-time dashboards)
+   - Epic 8: Notifications (Success Criteria: add email delivery tracking)
+
+   ❌ OBSOLETE (K Epics): No longer in initiative scope
+   - Epic 9: Legacy Data Migration (removed from scope)
+
+   ➕ CREATE (L Epics): New domains added
+   - Epic 17: Analytics Engine (new initiative requirement)
+   ```
+
+4. **Show Replan Summary:**
+   - Display operations for all Epics
+   - Show diffs for UPDATE operations (before/after Scope, Criteria)
+   - Show warnings for edge cases:
+     - ⚠️ "Epic 7 has 5 Stories In Progress - cannot auto-archive, manual review needed"
+   - Total operation count
+
+5. **User Confirmation:**
+   - Wait for user to type "confirm"
+   - If user provides feedback → Adjust operations and show updated summary
+
+6. **Execute Operations:**
+   - **KEEP:** Skip (no Linear API calls)
+   - **UPDATE:** Call `update_project(id, description=new_description)` (if no Stories In Progress)
+   - **OBSOLETE:** Call `update_project(id, state="archived")` (if no Stories In Progress)
+   - **CREATE:** Call `create_project()` (same as Phase 5a Step 3) + update kanban_board.md
+
+7. **Update kanban_board.md:**
+   - Remove OBSOLETE Epics from Epic Story Counters table
+   - Update modified Epics (UPDATE operations) - preserve Story counters
+   - Add new Epics (CREATE operations) to Epic Story Counters
+   - Update Epics Overview section (move archived to Archived section)
+
+**Output:** Summary message with operation results + affected Epic URLs
+
+**Important Constraints:**
+- **Never auto-update/archive Epics with Stories In Progress** (show warnings only)
+- **Never delete Epics:** Use state="archived" to preserve history
+- **Always require user confirmation** before executing operations
+
+---
+
+## Definition of Done
+
+Before completing work, verify ALL checkpoints:
+
+**✅ Discovery Complete (Phase 1):**
+- [ ] Team ID loaded from kanban_board.md
+- [ ] Next Epic Number loaded from kanban_board.md
+- [ ] Documentation scanned (requirements.md, architecture.md, tech_stack.md)
+- [ ] HTML files scanned (if frontend exists)
+- [ ] Infrastructure Epic decision made (YES/NO based on project conditions)
+
+**✅ Scope Analysis Complete (Phase 2):**
+- [ ] Domains auto-identified from docs + HTML
+- [ ] Infrastructure Epic (Epic 0) included if applicable
+- [ ] Epic list built (Epic 0-N or Epic 1-N)
+- [ ] User confirmed Epic structure (CONTROL POINT 1)
+
+**✅ Existing Epics Checked (Phase 3):**
+- [ ] Epic Story Counters read from kanban_board.md
+- [ ] Existing Epic count determined (0 → CREATE, ≥1 → REPLAN)
+
+**✅ Epic Preparation Complete (Phase 4 - CREATE only):**
+- [ ] Q1-Q5 auto-extracted for ALL domains
+- [ ] User provided missing information if needed (batch question)
+- [ ] ALL Epic documents generated (Epic 0-N indexes)
+
+**✅ Epic Creation Complete (Phase 5a - CREATE only):**
+- [ ] Batch preview shown with Epic 0-N indexes
+- [ ] User confirmed preview (CONTROL POINT 2)
+- [ ] ALL Epics created in Linear with "Epic {N}: {Title}" format (N = Next Epic Number)
+- [ ] kanban_board.md updated after EACH Epic:
+  - Next Epic Number incremented by 1
+  - Epic Story Counters row added
+  - Epics Overview updated
+- [ ] Summary displayed with all Epic URLs
+
+**✅ Epic Replan Complete (Phase 5b - REPLAN only):**
+- [ ] Existing Epics loaded from Linear
+- [ ] IDEAL plan compared against existing
+- [ ] Operations categorized (KEEP/UPDATE/OBSOLETE/CREATE)
+- [ ] User confirmed operations (CONTROL POINT 2)
+- [ ] Operations executed in Linear
+- [ ] kanban_board.md updated (removed OBSOLETE, added CREATE)
+- [ ] Summary displayed with affected Epic URLs
+
+**Output:** List of Linear Project URLs (Epic {N}: {Title}) + Next Epic Number value
+
+---
+
+## Example Usage
+
+**Request:**
+```
+"Create epics for e-commerce platform"
+```
+
+**Process:**
+
+1. **Phase 1: Discovery & Research**
+   - Team "Product", Next Epic Number = 11
+   - Scan requirements.md, architecture.md, tech_stack.md
+   - Scan HTML files: Found navigation with Products, Cart, Checkout
+   - Infrastructure Epic decision: YES (new project, multi-stack: React + Python)
+
+2. **Phase 2: Scope Analysis**
+   - Auto-identify 6 domains from docs + HTML: "Infrastructure", "User Management", "Product Catalog", "Shopping Cart", "Payment Processing", "Order Management"
+   - Build Epic list: Epic 0 (Infrastructure) + Epic 1-5 (business)
+   - Show proposed Epic structure → User confirms
+
+3. **Phase 3: Check Existing**
+   - Epic Story Counters: 0 rows → CREATE MODE
+
+4. **Phase 4: Epic Preparation**
+   - Auto-extract Q1-Q5 for all 6 domains from requirements.md, architecture.md, HTML
+   - Generate 6 Epic documents (Epic 0-5 indexes)
+
+5. **Phase 5a: Epic Creation**
+   - Show batch preview with Epic 0-5 indexes
+   - User types "confirm"
+   - Create in Linear sequentially:
+     - Epic 0 → Linear: "Epic 11: Infrastructure & Operations"
+     - Epic 1 → Linear: "Epic 12: User Management"
+     - Epic 2 → Linear: "Epic 13: Product Catalog"
+     - Epic 3 → Linear: "Epic 14: Shopping Cart"
+     - Epic 4 → Linear: "Epic 15: Payment Processing"
+     - Epic 5 → Linear: "Epic 16: Order Management"
+   - Next Epic Number updated to 17
+   - Display summary with all 6 URLs
+
+**Result:** 6 Epics created (Epic 0-5 internal indexes, Epic 11-16 Linear titles)
+
+---
+
+## Reference Files
+
+- **linear_integration.md:** Discovery patterns + Linear API reference
+- **epic_template_universal.md:** Epic template structure
+
+---
+
+## Best Practices
+
+- **Research project docs first:** Always scan requirements.md, architecture.md, tech_stack.md in Phase 1 Step 2 BEFORE asking user
+- **Scan HTML files:** Extract functional domains from navigation, forms, page titles (Phase 1 Step 2) - complements documentation
+- **Propose Infrastructure Epic:** For new projects, multi-stack, or projects with security/monitoring/deployment requirements (Phase 1 Step 3)
+- **Epic 0 for Infrastructure:** Use Epic 0 as reserved index for Infrastructure Epic within initiative, business domains start from Epic 1 (Phase 2 Step 2)
+- **Business Epic grouping:** Group domains by complete business process OR HTML screen
+  - ✅ BY BUSINESS PROCESS: "User Authentication" (login + register + password reset + profile)
+  - ✅ BY HTML SCREEN: "Product Catalog" (products list page + product details page + search)
+  - ❌ AVOID: "Login Screen", "Register Screen" as separate Epics (too granular, merge into "User Authentication")
+  - ❌ AVOID: "User Table", "Login Service" (technical components, not business domains)
+  - **Guideline:** 1 Epic = 5-10 User Stories = 1 complete business capability or major UI screen group
+- **Batch Epic preview:** Generate ALL Epics before showing preview - allows user to see complete Epic plan with Epic 0-N indexes (Phase 5a Step 1)
+- **Auto-extraction:** Extract Q1-Q5 from requirements.md, architecture.md, HTML BEFORE asking user (Phase 4 Step 1) - ask only for missing information
+- **Linear Title format:** "Epic {Next Epic Number}: {Domain}" where Next Epic Number from kanban_board.md (Phase 5a Step 3)
+- **Business-focused Scope:** Epic Scope In lists USER CAPABILITIES, not technical tasks
+  - ✅ GOOD: "Users can register, login, logout, reset password"
+  - ❌ BAD: "Create user table, JWT middleware, password hashing service"
+  - Technical architecture → Epic "Architecture Impact" section, NOT Scope In
+- **Measurable success criteria:** "<200ms" not "fast", ">98% login rate" not "reliable"
+- **Define OUT of scope:** Prevent scope creep with explicit exclusions
+- **No code snippets:** Never include actual code in Epic descriptions - only high-level features and goals
+
+---
+
+**Version:** 7.0.0 (BREAKING: Epic 0 clarified as initiative-internal index. HTML research added to Phase 1 Step 2 for frontend domain extraction. Phase structure simplified - removed old Phase 3 "Build IDEAL Plan" (merged into Phase 2 inline). Phase 4 extracted from Phase 5a for Epic Preparation. Phase numbering updated: Phase 3=Check Existing, Phase 4=Preparation, Phase 5a/5b=Creation/Replan. Linear titles use Next Epic Number consistently. Removed confusing "conceptual numbering" explanations.)
+**Last Updated:** 2025-11-20