learnship 2.1.2 → 2.2.0

package/learnship/templates/research-project/FEATURES.md

@@ -0,0 +1,130 @@
+# Features Research Template
+
+Template for `.planning/research/FEATURES.md` — feature landscape for the project domain.
+
+<template>
+
+```markdown
+# Feature Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Table Stakes
+
+Features users expect by default. Missing these = product feels incomplete.
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+
+## Differentiators
+
+Features that set the product apart. Not required for launch, but valuable.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+
+## Anti-Features
+
+Features that seem good but create problems. Prevent scope creep by documenting them.
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| [feature] | [surface appeal] | [actual problems] | [better approach] |
+| [feature] | [surface appeal] | [actual problems] | [better approach] |
+
+## Feature Dependencies
+
+```
+[Feature A]
+    └──requires──> [Feature B]
+                       └──requires──> [Feature C]
+
+[Feature D] ──enhances──> [Feature A]
+
+[Feature E] ──conflicts──> [Feature F]
+```
+
+### Dependency Notes
+
+- **[Feature A] requires [Feature B]:** [why the dependency exists]
+- **[Feature D] enhances [Feature A]:** [how they work together]
+- **[Feature E] conflicts with [Feature F]:** [why they're incompatible]
+
+## MVP Definition
+
+### Launch With (v1)
+
+Minimum viable product — what's needed to validate the concept.
+
+- [ ] [Feature] — [why essential]
+- [ ] [Feature] — [why essential]
+- [ ] [Feature] — [why essential]
+
+### Add After Validation (v1.x)
+
+Features to add once core is working.
+
+- [ ] [Feature] — [trigger for adding]
+- [ ] [Feature] — [trigger for adding]
+
+### Future Consideration (v2+)
+
+Features to defer until product-market fit is established.
+
+- [ ] [Feature] — [why defer]
+- [ ] [Feature] — [why defer]
+
+## Feature Prioritization Matrix
+
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+
+**Priority key:**
+- P1: Must have for launch
+- P2: Should have, add when possible
+- P3: Nice to have, future consideration
+
+---
+*Feature research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Table Stakes:**
+- These are non-negotiable for launch
+- Users don't give credit for having them, but penalize for missing them
+- Example: A community platform without user profiles is broken
+
+**Differentiators:**
+- These are where you compete
+- Should align with the Core Value from PROJECT.md
+- Don't try to differentiate on everything — pick 2-3
+
+**Anti-Features:**
+- Prevent scope creep by documenting what seems good but isn't
+- Include the alternative approach
+- Example: "Real-time everything" often creates complexity without value
+
+**Feature Dependencies:**
+- Critical for roadmap phase ordering
+- If A requires B, B must be in an earlier phase
+- Conflicts inform what NOT to combine in same phase
+
+**MVP Definition:**
+- Be ruthless about what's truly minimum
+- "Nice to have" is not MVP
+- Launch with less, validate, then expand
+
+</guidelines>

package/learnship/templates/research-project/PITFALLS.md

@@ -0,0 +1,102 @@
+# Pitfalls Research Template
+
+Template for `.planning/research/PITFALLS.md` — common mistakes and prevention strategies for the project domain.
+
+<template>
+
+```markdown
+# Pitfalls Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Common Mistakes
+
+| # | Mistake | Severity | Frequency | Impact |
+|---|---------|----------|-----------|--------|
+| 1 | [what goes wrong] | CRITICAL/HIGH/MEDIUM/LOW | [how often teams hit this] | [what breaks] |
+| 2 | [what goes wrong] | CRITICAL/HIGH/MEDIUM/LOW | [how often teams hit this] | [what breaks] |
+| 3 | [what goes wrong] | CRITICAL/HIGH/MEDIUM/LOW | [how often teams hit this] | [what breaks] |
+| 4 | [what goes wrong] | CRITICAL/HIGH/MEDIUM/LOW | [how often teams hit this] | [what breaks] |
+| 5 | [what goes wrong] | CRITICAL/HIGH/MEDIUM/LOW | [how often teams hit this] | [what breaks] |
+
+### Mistake Details
+
+**1. [Mistake name]**
+- **What happens:** [detailed description of the failure mode]
+- **Why it happens:** [root cause — usually a misunderstanding or shortcut]
+- **Example:** [concrete scenario]
+- **Fix cost:** [how expensive is it to fix after the fact]
+
+**2. [Mistake name]**
+- **What happens:** [detailed description]
+- **Why it happens:** [root cause]
+- **Example:** [concrete scenario]
+- **Fix cost:** [cost to fix later]
+
+## Warning Signs
+
+Early indicators that a project is heading toward common pitfalls:
+
+| Warning Sign | Indicates | Action |
+|-------------|-----------|--------|
+| [observable symptom] | [which mistake is brewing] | [what to do immediately] |
+| [observable symptom] | [which mistake is brewing] | [what to do immediately] |
+| [observable symptom] | [which mistake is brewing] | [what to do immediately] |
+
+## Prevention Strategies
+
+Proactive measures to avoid the mistakes above:
+
+| Strategy | Prevents | When to Apply | How |
+|----------|----------|---------------|-----|
+| [strategy name] | [mistake #N] | [at what phase/stage] | [concrete implementation steps] |
+| [strategy name] | [mistake #N] | [at what phase/stage] | [concrete implementation steps] |
+| [strategy name] | [mistake #N] | [at what phase/stage] | [concrete implementation steps] |
+
+## Domain-Specific Patterns
+
+### Patterns That Look Right But Aren't
+
+| Pattern | Why It Seems Good | Actual Problem | Better Approach |
+|---------|-------------------|----------------|-----------------|
+| [pattern] | [surface appeal] | [hidden issue] | [what to do instead] |
+| [pattern] | [surface appeal] | [hidden issue] | [what to do instead] |
+
+### Patterns That Look Wrong But Work
+
+| Pattern | Why It Seems Bad | Why It Actually Works | When to Use |
+|---------|------------------|----------------------|-------------|
+| [pattern] | [surface concern] | [deeper reason] | [specific conditions] |
+
+---
+*Pitfalls research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Common Mistakes:**
+- Rank by severity — CRITICAL mistakes should be listed first
+- Include fix cost — some mistakes are cheap to fix later, others are architectural
+- Be specific: "not handling auth token refresh" not "bad auth"
+
+**Warning Signs:**
+- These are observable symptoms, not the mistakes themselves
+- Help the executor recognize when things are going wrong mid-implementation
+- Each warning sign should map to a specific mistake
+
+**Prevention Strategies:**
+- Must be actionable — "be careful" is not a strategy
+- Include when to apply (during planning, during implementation, during testing)
+- Reference specific mistakes they prevent
+
+**Domain-Specific Patterns:**
+- "Looks right but isn't" catches cargo-cult patterns
+- "Looks wrong but works" prevents premature optimization of working patterns
+- Both require domain expertise to identify
+
+</guidelines>

package/learnship/templates/research-project/STACK.md

@@ -0,0 +1,105 @@
+# Stack Research Template
+
+Template for `.planning/research/STACK.md` — recommended technologies for the project domain.
+
+<template>
+
+```markdown
+# Stack Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Recommended Stack
+
+### Core Technologies
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+
+### Supporting Libraries
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| [name] | [version] | [what it does] | [specific use case] |
+| [name] | [version] | [what it does] | [specific use case] |
+
+### Development Tools
+
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| [name] | [what it does] | [configuration tips] |
+| [name] | [what it does] | [configuration tips] |
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| [our choice] | [other option] | [conditions where alternative is better] |
+| [our choice] | [other option] | [conditions where alternative is better] |
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| [technology] | [specific problem] | [recommended alternative] |
+| [technology] | [specific problem] | [recommended alternative] |
+
+## Versions
+
+### Version Compatibility
+
+| Package A | Compatible With | Notes |
+|-----------|-----------------|-------|
+| [package@version] | [package@version] | [compatibility notes] |
+
+### Installation
+
+```bash
+# Core
+[package manager] install [packages]
+
+# Supporting
+[package manager] install [packages]
+
+# Dev dependencies
+[package manager] install -D [packages]
+```
+
+---
+*Stack research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Core Technologies:**
+- Include specific version numbers — not just "React" but "React 19.x"
+- Explain why this is the standard choice, not just what it does
+- Focus on technologies that affect architecture decisions
+
+**Supporting Libraries:**
+- Include libraries commonly needed for this domain
+- Note when each is needed (not all projects need all libraries)
+
+**Alternatives:**
+- Don't just dismiss alternatives — explain when they make sense
+- Helps the user make informed decisions if they disagree with recommendations
+
+**What NOT to Use:**
+- Actively warn against outdated or problematic choices
+- Explain the specific problem, not just "it's old"
+- Always provide the recommended alternative
+
+**Versions:**
+- Note any known compatibility issues between packages
+- Critical for avoiding debugging time later
+- Include installation commands so the planner can reference them
+
+</guidelines>

package/learnship/templates/research-project/SUMMARY.md

@@ -0,0 +1,111 @@
+# Summary Research Template
+
+Template for `.planning/research/SUMMARY.md` — synthesis of all research findings into actionable guidance.
+
+<template>
+
+```markdown
+# Research Summary
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Recommended Stack
+
+### Primary Technologies
+
+| Technology | Version | Role |
+|------------|---------|------|
+| [name] | [version] | [primary purpose in this project] |
+| [name] | [version] | [primary purpose in this project] |
+| [name] | [version] | [primary purpose in this project] |
+
+### Key Stack Decisions
+
+- **[Decision 1]:** [rationale — why this over alternatives]
+- **[Decision 2]:** [rationale]
+- **[Decision 3]:** [rationale]
+
+## Table Stakes Features
+
+Features that must be in v1 — users expect these by default:
+
+- [ ] [Feature] — [one-line description]
+- [ ] [Feature] — [one-line description]
+- [ ] [Feature] — [one-line description]
+- [ ] [Feature] — [one-line description]
+
+## Key Architecture Decisions
+
+### System Shape
+
+[1-2 sentences describing the overall architecture pattern — e.g., "Monolithic Next.js app with server components, Postgres via Prisma ORM, and Stripe for payments."]
+
+### Critical Boundaries
+
+| Boundary | What It Separates | Why It Matters |
+|----------|-------------------|----------------|
+| [boundary] | [side A] / [side B] | [architectural significance] |
+| [boundary] | [side A] / [side B] | [architectural significance] |
+
+### Recommended Build Order
+
+1. [Component] — [why first]
+2. [Component] — [depends on #1]
+3. [Component] — [depends on #1, #2]
+4. [Component] — [depends on previous]
+
+## Top Pitfalls
+
+The most dangerous mistakes for this domain, ranked by severity:
+
+| # | Pitfall | Severity | Prevention |
+|---|---------|----------|------------|
+| 1 | [mistake] | CRITICAL | [one-line prevention strategy] |
+| 2 | [mistake] | HIGH | [one-line prevention strategy] |
+| 3 | [mistake] | HIGH | [one-line prevention strategy] |
+| 4 | [mistake] | MEDIUM | [one-line prevention strategy] |
+| 5 | [mistake] | MEDIUM | [one-line prevention strategy] |
+
+## Primary Recommendation
+
+[One paragraph — the single most important takeaway from this research. What should the planner prioritize above all else?]
+
+---
+*Research summary for: [domain]*
+*Researched: [date]*
+*Sources: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md*
+```
+
+</template>
+
+<guidelines>
+
+**Purpose:**
+- This file synthesizes the other 4 research files into a single actionable reference
+- The planner reads this file first — it should contain everything needed to start planning
+- Keep it concise: tables and bullet points, not paragraphs
+
+**Recommended Stack:**
+- Only include the primary technologies — no supporting libraries
+- Key decisions explain WHY, not just WHAT
+
+**Table Stakes Features:**
+- Pull directly from FEATURES.md Table Stakes section
+- These become the v1 must_haves in requirements
+
+**Key Architecture Decisions:**
+- System shape in 1-2 sentences — enough for the planner to understand the pattern
+- Build order feeds directly into roadmap phase ordering
+
+**Top Pitfalls:**
+- Maximum 5 — the most dangerous ones only
+- Each must have a one-line prevention strategy
+- These become verification checkpoints during execution
+
+**Primary Recommendation:**
+- One paragraph, one decision
+- This is what the planner optimizes for
+
+</guidelines>

package/learnship/workflows/challenge.md

@@ -138,10 +138,22 @@ Proposal: [description]
 [If PROCEED: key risks to monitor]
 ```
 
-Present the verdict using the platform's blocking question tool:
-- **Proceed as planned** → continue to planning
-- **Adjust scope** → describe adjustments, then re-challenge or proceed
-- **Rethink** → go back to ideation or discussion
+Present the verdict using a structured question:
+
+```
+AskUserQuestion([
+  {
+    header: "Challenge Verdict",
+    question: "Based on the product and engineering analysis — how do you want to proceed?",
+    multiSelect: false,
+    options: [
+      { label: "Proceed as planned", description: "Continue to planning with identified risks monitored" },
+      { label: "Adjust scope", description: "Narrow the scope based on challenge findings, then proceed" },
+      { label: "Rethink", description: "Go back to ideation or discussion — too many concerns" }
+    ]
+  }
+])
+```
 
 ## Step 5: Record Decision
 

package/learnship/workflows/debug.md

@@ -35,14 +35,38 @@ description: [description]
 
 ## Step 2: Triage
 
-Ask: **"What is the exact symptom?"**
+If no description was provided as an argument, ask: **"What is the exact symptom?"** and wait for response.
 
-If description was provided as an argument, use it as starting context. Then ask follow-up questions one at a time:
+If description was provided, use it as starting context. Then gather triage details using structured questions:
 
-1. "When does this happen? Always, sometimes, or only under specific conditions?"
-2. "What did you expect to happen?"
-3. "When did it start? Was it working before? What changed?"
-4. "What have you already tried?"
+```
+AskUserQuestion([
+  {
+    header: "Frequency",
+    question: "When does this happen?",
+    multiSelect: false,
+    options: [
+      { label: "Always", description: "Reproduces every time" },
+      { label: "Sometimes", description: "Intermittent, not always reproducible" },
+      { label: "Specific conditions", description: "Only under certain circumstances" }
+    ]
+  },
+  {
+    header: "Regression",
+    question: "When did it start?",
+    multiSelect: false,
+    options: [
+      { label: "Always been broken", description: "Never worked correctly" },
+      { label: "Recently broke", description: "Was working before, something changed" },
+      { label: "Not sure", description: "Don't know when it started" }
+    ]
+  }
+])
+```
+
+Then ask as follow-ups (one at a time):
+- "What did you expect to happen?"
+- "What have you already tried?"
 
 After gathering answers, write a triage summary to the session file:
 ```markdown

package/learnship/workflows/diagnose-issues.md

@@ -107,7 +107,20 @@ Files: [list]
 Effort: small | medium | large
 ```
 
-Ask: "Does this diagnosis look right? Proceed with creating fix plans?"
+```
+AskUserQuestion([
+  {
+    header: "Diagnosis Review",
+    question: "Does this diagnosis look right?",
+    multiSelect: false,
+    options: [
+      { label: "Proceed", description: "Diagnosis is correct — create fix plans" },
+      { label: "Revise", description: "Something is off — let me provide corrections" },
+      { label: "Cancel", description: "Stop here — I'll investigate manually" }
+    ]
+  }
+])
+```
 
 ## Step 6: Create Fix Plans
 

package/learnship/workflows/discuss-milestone.md

@@ -33,7 +33,21 @@ Check if a MILESTONE-CONTEXT.md already exists:
 node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/MILESTONE-CONTEXT.md') ? 'EXISTS' : 'MISSING')"
 ```
 
-If exists: ask "A milestone context file already exists from a prior discussion. Update it or start fresh?"
+If exists:
+
+```
+AskUserQuestion([
+  {
+    header: "Existing Context",
+    question: "A milestone context file already exists from a prior discussion.",
+    multiSelect: false,
+    options: [
+      { label: "Update it", description: "Add to or revise existing milestone context" },
+      { label: "Start fresh", description: "Discard prior context and start over" }
+    ]
+  }
+])
+```
 
 ## Step 2: Discuss Goals
 

package/learnship/workflows/discuss-phase.md

@@ -56,13 +56,40 @@ Note any decisions that constrain or inform this phase's approach. Surface them
 ls .planning/phases/*-CONTEXT.md 2>/dev/null
 ```
 
-If CONTEXT.md already exists for this phase:
-- Offer: **Update it** / **View it** / **Skip** (use as-is)
-- If "Skip" → exit workflow
+If CONTEXT.md already exists for this phase, present the choice:
+
+```
+AskUserQuestion([
+  {
+    header: "Existing Context",
+    question: "CONTEXT.md already exists for this phase. What do you want to do?",
+    multiSelect: false,
+    options: [
+      { label: "Update it", description: "Add to or revise existing decisions" },
+      { label: "View it", description: "Show current context, then decide" },
+      { label: "Skip", description: "Use existing context as-is" }
+    ]
+  }
+])
+```
+
+If "Skip" → exit workflow.
 
 If no CONTEXT.md exists but plans already exist for this phase:
-- Warn: "Phase [X] already has plans created without user context. Your decisions here won't affect existing plans unless you re-run plan-phase."
-- Ask: **Continue and replan after** / **Cancel**
+
+```
+AskUserQuestion([
+  {
+    header: "Plans Already Exist",
+    question: "Phase [X] already has plans created without user context. Your decisions here won't affect existing plans unless you re-run plan-phase.",
+    multiSelect: false,
+    options: [
+      { label: "Continue and replan after", description: "Capture decisions now, re-run plan-phase later" },
+      { label: "Cancel", description: "Keep existing plans unchanged" }
+    ]
+  }
+])
+```
 
 ## Step 3: Scout Codebase
 
@@ -119,20 +146,66 @@ Carrying forward from earlier phases:
 - [Decision from Phase N]
 ```
 
-Present 3-4 gray areas for selection (multi-select). Annotate with:
-- Prior decision context: "You chose X in Phase 5"
-- Code context: "You already have a Card component with shadow/rounded variants"
+Present gray areas using a structured multi-select question. Annotate with prior decisions and code context:
+
+```
+AskUserQuestion([
+  {
+    header: "Gray Areas",
+    question: "Which areas do you want to discuss? (select all that apply)",
+    multiSelect: true,
+    options: [
+      { label: "[Area 1]", description: "[Prior context or code context annotation]" },
+      { label: "[Area 2]", description: "[Prior context or code context annotation]" },
+      { label: "[Area 3]", description: "[Prior context or code context annotation]" },
+      { label: "All clear — skip discussion", description: "No gray areas need clarification" }
+    ]
+  }
+])
+```
+
+If "All clear" → skip to Step 6.
 
 **For each selected area, discuss:**
 
 1. Announce: "Let's talk about [Area]."
-2. Ask 4 focused questions with concrete options (not abstract). Include the recommended choice. Annotate options with existing code where relevant.
+2. Ask focused questions with concrete options using structured questions where possible:
+
+```
+AskUserQuestion([
+  {
+    header: "[Area]: [Decision Point]",
+    question: "[Specific implementation question]",
+    multiSelect: false,
+    options: [
+      { label: "[Option A] (Recommended)", description: "[Why, with code context if relevant]" },
+      { label: "[Option B]", description: "[Why]" },
+      { label: "[Option C]", description: "[Why]" }
+    ]
+  }
+])
+```
+
 3. After 4 questions, ask: "More questions about [area], or move to next?"
 4. If more → ask 4 more, then check again
 
 After all selected areas:
 - Summarize decisions captured
-- Ask: "Which gray areas remain unclear?" → "Explore more" or "I'm ready for context"
+- Present final check:
+
+```
+AskUserQuestion([
+  {
+    header: "Wrap Up",
+    question: "All gray areas discussed. Ready to generate CONTEXT.md?",
+    multiSelect: false,
+    options: [
+      { label: "Ready", description: "Generate CONTEXT.md with captured decisions" },
+      { label: "Explore more", description: "Discuss additional areas before writing context" }
+    ]
+  }
+])
+```
 
 <scope_guardrail>
 **No scope creep.** The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.