learnship 2.1.2 → 2.2.1

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

@@ -0,0 +1,140 @@
+# Architecture Research Template
+
+Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
+
+<template>
+
+```markdown
+# Architecture Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Component Boundaries
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        [Layer Name]                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+│  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │        │
+│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│       │            │            │            │              │
+├───────┴────────────┴────────────┴────────────┴──────────────┤
+│                        [Layer Name]                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                    [Component]                       │    │
+│  └─────────────────────────────────────────────────────┘    │
+├─────────────────────────────────────────────────────────────┤
+│                        [Layer Name]                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │ [Store]  │  │ [Store]  │  │ [Store]  │                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| [name] | [what it owns] | [how it's usually built] |
+| [name] | [what it owns] | [how it's usually built] |
+| [name] | [what it owns] | [how it's usually built] |
+
+## Data Flow
+
+### Primary Data Flow
+
+```
+[Source] → [Transform/Process] → [Destination]
+   ↓
+[Side Effect / Event]
+   ↓
+[Consumer]
+```
+
+### Data Flow Description
+
+| Flow | Source | Destination | Format | Notes |
+|------|--------|-------------|--------|-------|
+| [name] | [where data originates] | [where it goes] | [JSON/binary/stream] | [important details] |
+| [name] | [where data originates] | [where it goes] | [JSON/binary/stream] | [important details] |
+
+## Build Order
+
+Suggested implementation sequence based on dependencies:
+
+| Order | Component | Dependencies | Rationale |
+|-------|-----------|--------------|-----------|
+| 1 | [component] | None | [why first — usually data layer or core abstractions] |
+| 2 | [component] | [depends on #1] | [why this order] |
+| 3 | [component] | [depends on #1, #2] | [why this order] |
+| 4 | [component] | [depends on #2, #3] | [why this order] |
+
+## Integration Points
+
+### External Integrations
+
+| Integration | Type | Protocol | Auth | Notes |
+|------------|------|----------|------|-------|
+| [service] | [API/SDK/webhook] | [REST/gRPC/WS] | [key/OAuth/none] | [rate limits, gotchas] |
+
+### Internal Boundaries
+
+| Boundary | Left Side | Right Side | Contract |
+|----------|-----------|------------|----------|
+| [name] | [module A] | [module B] | [interface/API shape] |
+
+## Recommended Project Structure
+
+```
+src/
+├── [folder]/           # [purpose]
+│   ├── [subfolder]/    # [purpose]
+│   └── [file].ts       # [purpose]
+├── [folder]/           # [purpose]
+│   ├── [subfolder]/    # [purpose]
+│   └── [file].ts       # [purpose]
+├── [folder]/           # [purpose]
+└── [folder]/           # [purpose]
+```
+
+---
+*Architecture research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Component Boundaries:**
+- Use ASCII diagrams for system overview — they render in any terminal or editor
+- Each component should have a single clear responsibility
+- If a component does two things, it should probably be two components
+
+**Data Flow:**
+- Show the primary happy path first, then edge cases
+- Note data format at each boundary (JSON, binary, stream)
+- Identify where data transforms happen — these are common bug sources
+
+**Build Order:**
+- This directly feeds into roadmap phase ordering
+- Always start with the data layer or core abstractions
+- UI comes last (it depends on everything below it)
+
+**Integration Points:**
+- Note rate limits, auth requirements, and known gotchas
+- External integrations are the most common source of runtime failures
+- Define internal boundaries as interfaces/contracts — this enables parallel work
+
+**Project Structure:**
+- Follow domain conventions (e.g., Next.js app/ router, Django apps/)
+- Group by feature, not by type, for most projects
+- Keep the structure flat enough to navigate but deep enough to organize
+
+</guidelines>

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