learnship 2.0.10 → 2.1.0

package/learnship/workflows/extract-learnings.md

@@ -0,0 +1,161 @@
+---
+description: Extract structured learnings from completed phase artifacts — decisions, lessons, patterns, surprises
+---
+
+# Extract Learnings
+
+Extract decisions, lessons learned, patterns discovered, and surprises encountered from completed phase artifacts into a structured LEARNINGS.md file. Captures institutional knowledge that would otherwise be lost between phases.
+
+**Usage:** `extract-learnings [N]` — extract from phase N
+
+**Complements `/compound`:** compound captures reusable solutions, extract-learnings captures meta-knowledge (why things worked, what surprised you, what patterns emerged).
+
+## Step 1: Initialize
+
+Find the phase directory:
+```bash
+ls ".planning/phases/" | grep "^[0-9]" | sort
+```
+
+Find the phase matching `[N]`. If not found, stop and list available phases.
+
+Verify required artifacts exist:
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-PLAN.md 2>/dev/null
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-SUMMARY.md 2>/dev/null
+```
+
+If PLAN.md or SUMMARY.md files are missing: "Required artifacts missing. PLAN.md and SUMMARY.md are required for learning extraction."
+
+## Step 2: Collect Artifacts
+
+**Required (must exist):**
+- All `*-PLAN.md` files for the phase
+- All `*-SUMMARY.md` files for the phase
+
+**Optional (read if available, skip if not):**
+- `*-VERIFICATION.md` — verification results
+- `*-UAT.md` — user acceptance test results
+- `*-SECURITY.md` — security verification
+- `.planning/STATE.md` — project state with decisions and blockers
+
+Track which optional artifacts are missing for the frontmatter.
+
+## Step 3: Extract Learnings
+
+Analyze all collected artifacts and extract learnings into 4 categories:
+
+### 1. Decisions
+Technical and architectural decisions made during the phase:
+- Explicit decisions documented in PLAN.md or SUMMARY.md
+- Technology choices and their rationale
+- Trade-offs that were evaluated
+
+Each entry: **What** was decided, **Why** (rationale), **Source** (which artifact).
+
+### 2. Lessons
+What worked well and what didn't:
+- Approaches that succeeded or failed
+- Time estimates vs actual (if observable from git timestamps)
+- Unexpected complexity or simplicity
+
+Each entry: **What happened**, **Why it matters**, **Source**.
+
+### 3. Patterns
+Reusable patterns that emerged:
+- Code patterns used across multiple tasks
+- Process patterns that worked well
+- Integration patterns between components
+
+Each entry: **Pattern name**, **When to use**, **Source**.
+
+### 4. Surprises
+Things that didn't go as expected:
+- Unexpected bugs or behaviors
+- Assumptions that were wrong
+- External factors that affected the work
+
+Each entry: **What was surprising**, **Impact**, **Source**.
+
+## Step 4: Write LEARNINGS.md
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-LEARNINGS.md`:
+
+```markdown
+---
+phase: [N]
+phase_name: [name]
+extracted: [date]
+plan_count: [N]
+summary_count: [N]
+missing_artifacts: [list or "none"]
+---
+
+# Phase [N]: [Name] — Learnings
+
+## Decisions
+
+### D1: [Decision title]
+**What:** [what was decided]
+**Why:** [rationale]
+**Source:** [artifact file]
+
+## Lessons
+
+### L1: [Lesson title]
+**What happened:** [description]
+**Why it matters:** [impact on future work]
+**Source:** [artifact file]
+
+## Patterns
+
+### P1: [Pattern name]
+**When to use:** [conditions]
+**Source:** [artifact file]
+
+## Surprises
+
+### S1: [Surprise title]
+**What was surprising:** [description]
+**Impact:** [how it affected the work]
+**Source:** [artifact file]
+
+---
+
+*Extracted from Phase [N] artifacts on [date]*
+```
+
+## Step 5: Commit and Report
+
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-LEARNINGS.md"
+git commit -m "docs([padded_phase]): extract phase learnings"
+```
+
+```
+learnship > LEARNINGS EXTRACTED
+
+Phase [N]: [Name]
+Decisions: [N]  |  Lessons: [N]  |  Patterns: [N]  |  Surprises: [N]
+
+Report: [path to LEARNINGS.md]
+
+These learnings feed into future planning — the planner will reference them
+when working on related phases.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** You just extracted meta-knowledge from a phase. Make it stick:
+>
+> `@agentic-learning space` — Schedule the key patterns and lessons for spaced review. The extraction just identified WHAT you learned — spacing ensures you RETAIN it.
+>
+> `@agentic-learning interleave [phase topic]` — Mix these learnings with concepts from earlier phases to strengthen cross-cutting understanding.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning space` to schedule these learnings for spaced review."*

package/learnship/workflows/forensics.md

@@ -0,0 +1,118 @@
+---
+description: Post-mortem investigation for failed or stuck workflows — read-only diagnostic report
+---
+
+# Forensics
+
+Post-mortem investigation for failed or stuck workflows. Analyzes git history, `.planning/` artifacts, and file system state to detect anomalies and generate a structured diagnostic report.
+
+**Usage:** `forensics` or `forensics [problem description]`
+
+**Principle:** This is a read-only investigation. Do not modify project files. Only write the forensic report.
+
+## Step 1: Get Problem Description
+
+If a description was provided as an argument, use it. Otherwise ask:
+
+> "What went wrong? Describe the issue."
+
+Record the problem description for the report.
+
+## Step 2: Gather Evidence
+
+Collect data from all available sources. Missing sources are fine — adapt to what exists.
+
+### 2a. Git History
+
+```bash
+git log --oneline -30
+git log --format="%H %ai %s" -30
+git log --name-only --format="" -20 | sort | uniq -c | sort -rn | head -20
+git status --short
+git diff --stat
+```
+
+Record:
+- Commit timeline (dates, messages, frequency)
+- Most-edited files (potential stuck-loop indicator)
+- Uncommitted changes (potential crash/interruption indicator)
+
+### 2b. Planning State
+
+Read these files if they exist:
+- `.planning/STATE.md` — current milestone, phase, progress, blockers
+- `.planning/ROADMAP.md` — phase list with status
+- `.planning/config.json` — workflow configuration
+
+### 2c. Phase Artifacts
+
+```bash
+ls .planning/phases/*/
+```
+
+For each phase, check which artifacts exist (PLAN, SUMMARY, VERIFICATION, CONTEXT, RESEARCH, UAT). Track which phases have complete artifact sets vs gaps.
+
+## Step 3: Analyze Anomalies
+
+| Pattern | Indicates | Severity |
+|---------|-----------|----------|
+| Same file edited 5+ times in 20 commits | Stuck execution loop | High |
+| PLAN.md exists but no SUMMARY.md | Execution interrupted | Medium |
+| Large time gap between consecutive commits | Session interrupted or context exhausted | Medium |
+| VERIFICATION.md with `gaps_found` | Phase incomplete | Medium |
+| STATE.md references non-existent phase dir | State/filesystem mismatch | High |
+| Uncommitted changes + old timestamps | Abandoned session | Low |
+
+## Step 4: Determine Root Cause
+
+| Category | Description | Recovery |
+|----------|-------------|----------|
+| **Execution stuck** | Agent looped on same files/tests | Re-run with `--wave` or fix trigger |
+| **Context exhaustion** | Agent ran out of context mid-phase | Break into smaller plans, re-run |
+| **Session interrupted** | Human or system terminated mid-work | Resume with `/resume-work` |
+| **State mismatch** | STATE.md doesn't match filesystem | Manual STATE.md correction |
+| **Plan deficiency** | Plans were wrong | Re-plan with `plan-phase --gaps` |
+| **External failure** | API, dependency, or environment issue | Fix external issue, re-run |
+
+## Step 5: Write Forensic Report
+
+```bash
+node -e "require('fs').mkdirSync('.planning/reports',{recursive:true})"
+```
+
+Write `.planning/reports/FORENSIC-[YYYY-MM-DD].md` with: evidence summary, anomalies detected, root cause (category + explanation + confidence), recommended recovery steps, and prevention advice.
+
+Commit:
+```bash
+git add .planning/reports/
+git commit -m "docs: forensic report"
+```
+
+## Step 6: Present Findings
+
+```
+learnship > FORENSIC REPORT COMPLETE
+
+Root Cause: [category] — [one-line explanation]
+Confidence: [high/medium/low]
+
+Recovery:
+1. [action]
+2. [action]
+
+Report: .planning/reports/FORENSIC-[date].md
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Failures are high-signal learning opportunities:
+>
+> `@agentic-learning reflect` — What pattern caused this failure? What would you watch for next time? Structured reflection on failures builds diagnostic intuition.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to extract lessons from this failure."*

package/learnship/workflows/help.md

@@ -16,7 +16,7 @@ You only need to remember **5 commands** to use learnship effectively:
 | `/next` | Auto-pilot — reads state and runs the right workflow for you |
 | `/new-project` | Starting a brand new project |
 | `/quick "..."` | One-off task with atomic commit, no ceremony |
-| `/help` | This screen — see all 49 commands |
+| `/help` | This screen — see all 57 commands |
 
 Everything else below is discoverable from `/ls` as you go.
 
@@ -87,9 +87,11 @@ Everything else below is discoverable from `/ls` as you go.
 | `/review [mode]` | Multi-persona code review (correctness, testing, security, performance, maintainability) |
 | `/challenge [description]` | Product + engineering challenge gate — is this worth building? |
 | `/ship` | Ship pipeline: test → lint → commit → push → PR |
-| `/ideate [focus]` | Codebase-grounded divergent thinking — discover what to work on |
+| `/ideate [focus]` | Codebase-grounded divergent thinking — discover what to work on (`--explore` for Socratic mode) |
 | `/guard [scope\|off]` | Safety mode — warn on destructive commands, lock file scope |
 | `/sync-docs` | Detect stale documentation after code changes |
+| `/docs-update` | Generate, update, and verify project documentation |
+| `/secure-phase [N]` | Per-phase STRIDE security verification |
 
 ### Decision Intelligence — institutional memory
 
@@ -99,6 +101,22 @@ Everything else below is discoverable from `/ls` as you go.
 | `/knowledge-base` | Aggregate all decisions + lessons into searchable KNOWLEDGE.md |
 | `/knowledge-base search [query]` | Search the project knowledge base |
 
+### Recovery — when things go wrong
+
+| Workflow | What it does |
+|----------|-------------|
+| `/forensics [problem]` | Post-mortem investigation for failed/stuck workflows (read-only) |
+| `/undo --last N\|--phase NN\|--plan NN-MM` | Safe git revert — preserves history, checks dependencies |
+
+### Session — capture and report
+
+| Workflow | What it does |
+|----------|-------------|
+| `/note [text]` | Zero-friction idea capture — no questions, just write |
+| `/session-report` | Post-session summary for stakeholder sharing |
+| `/extract-learnings [N]` | Structured learning extraction from phase artifacts |
+| `/milestone-summary [version]` | Comprehensive milestone summary for team onboarding |
+
 ### Milestone Intelligence — reflect and hand off
 
 | Workflow | What it does |

package/learnship/workflows/ideate.md

@@ -4,10 +4,11 @@ description: Codebase-grounded divergent thinking — discover what is worth wor
 
 # Ideate
 
-Codebase-grounded divergent ideation. Scans the actual codebase for hotspots, TODOs, test gaps, and friction points, then generates 15-25 improvement ideas across multiple thinking frames. Adversarial filter eliminates weak ideas. Presents top 5-7 ranked survivors.
+Codebase-grounded divergent ideation with Socratic exploration. Two modes: **scan mode** (default) scans the actual codebase for hotspots and generates ranked improvement ideas. **Explore mode** (`--explore`) uses Socratic questioning to help you think through an idea before committing to artifacts.
 
-**Usage:** `ideate` — open-ended ideation on the current project
+**Usage:** `ideate` — open-ended scan-based ideation on the current project
 **Usage:** `ideate [focus]` — focused ideation on a specific area, concept, or constraint
+**Usage:** `ideate --explore [topic]` — Socratic exploration of an idea with mid-conversation research
 
 **Sequencing:** Run between milestones — after `/complete-milestone`, before `/discuss-milestone` or `/new-milestone`. Requires an existing project with `AGENTS.md` and `.planning/`.
 
@@ -26,7 +27,14 @@ ls AGENTS.md 2>/dev/null && ls .planning/PROJECT.md 2>/dev/null
 
 **If project exists:** Continue.
 
-## Step 2: Scope
+## Step 2: Mode Selection
+
+Parse arguments for `--explore` flag.
+
+**If `--explore` is present:** Jump to Step 2b (Socratic Exploration).
+**Otherwise:** Continue to Step 2a (Scan Mode).
+
+## Step 2a: Scope (Scan Mode)
 
 If a focus argument was provided, use it as the ideation lens.
 If no argument, proceed with open-ended ideation.
@@ -38,7 +46,57 @@ find .planning/ -name "*-ideation-*.md" -mtime -30 2>/dev/null
 
 If recent ideation exists, ask: "Found recent ideation work. Resume from it, or start fresh?"
 
-## Step 3: Codebase Scan
+## Step 2b: Socratic Exploration (only with `--explore`)
+
+If a topic was provided, acknowledge it and begin exploring:
+```
+## Explore: {topic}
+
+Let's think through this together. I'll ask questions to help clarify the idea
+before we commit to any artifacts.
+```
+
+If no topic, ask:
+```
+## Explore
+
+What's on your mind? This could be a feature idea, an architectural question,
+a problem you're trying to solve, or something you're not sure about yet.
+```
+
+**Conversation rules (2-5 exchanges):**
+- Ask **one question at a time** (never a list of questions)
+- Questions should probe: constraints, tradeoffs, users, scope, dependencies, risks
+- Listen for signals: "or" / "versus" / "tradeoff" indicate competing priorities worth exploring
+- Reflect back what you hear to confirm understanding before moving forward
+- **Follow the user's energy** — if they're excited about one aspect, go deeper there
+
+**Mid-conversation research offer (after 2-3 exchanges):**
+
+If the conversation surfaces factual questions, technology comparisons, or unknowns:
+```
+This touches on [specific question]. Want me to do a quick research pass before we continue?
+This would take ~30 seconds and might surface useful context.
+
+[Yes, research this] / [No, let's keep exploring]
+```
+
+If yes and parallelization is enabled, spawn a research agent. Otherwise do an inline research pass. Share findings and continue.
+
+**Crystallize outputs (after 3-6 exchanges):**
+
+When the conversation reaches natural conclusions, propose **up to 4 outputs**:
+
+| Type | Destination | When to suggest |
+|------|-------------|----------------|
+| Note | `.planning/notes/{slug}.md` | Observations, context, decisions worth remembering |
+| Todo | via `/add-todo` | Concrete actionable tasks identified |
+| Decision | via `/decision-log` | Architectural or scope decisions made |
+| Phase proposal | via `/add-phase` | Idea crystallized into a deliverable phase |
+
+Write selected outputs, then jump to Step 7 (Present Results) with a tailored summary.
+
+## Step 3: Codebase Scan (Scan Mode)
 
 Gather grounding context before generating ideas:
 
@@ -175,6 +233,7 @@ git commit -m "docs: ideation — [focus or 'open-ended'] ([N] survivors)"
 Present the "What's next?" options using the platform's blocking question tool:
 
 - **Deep-dive an idea** → expand on the selected idea with more detail
+- **Explore an idea** → run `ideate --explore [idea]` for Socratic deep-dive
 - **Add to current milestone** → feed into `/add-phase`
 - **Start a new milestone** → feed into `/discuss-milestone` then `/new-milestone`
 - **Challenge an idea** → run `/challenge [idea]` to stress-test it

package/learnship/workflows/ls.md

@@ -148,4 +148,4 @@ If the user says yes (or "go", "do it", "run it", "proceed") — immediately inv
 
 - `/ls` is an alias for the status + routing logic in `progress`. Use either.
 - For full auto-pilot (no prompt), use `/next` instead.
-- To see all 49 available commands: `/help`
+- To see all 57 available commands: `/help`

package/learnship/workflows/milestone-summary.md

@@ -0,0 +1,150 @@
+---
+description: Generate a comprehensive milestone summary for team onboarding — a new contributor reads it and understands the project
+---
+
+# Milestone Summary
+
+Generate a comprehensive, human-friendly project summary from completed milestone artifacts. Designed for team onboarding — a new contributor can read the output and understand the entire project.
+
+**Usage:** `milestone-summary` or `milestone-summary [version]`
+
+## Step 1: Resolve Version
+
+If a version was provided, use it. Otherwise:
+1. Check `.planning/STATE.md` for current milestone version
+2. Check `.planning/milestones/` for the latest archived version
+3. If nothing found: "No milestone found. Run `/new-project` or `/new-milestone` first."
+
+## Step 2: Locate Artifacts
+
+**Archived milestone** (`.planning/milestones/v{VERSION}-ROADMAP.md` exists):
+```
+ROADMAP_PATH=".planning/milestones/v${VERSION}-ROADMAP.md"
+REQUIREMENTS_PATH=".planning/milestones/v${VERSION}-REQUIREMENTS.md"
+```
+
+**Current/in-progress milestone** (no archive yet):
+```
+ROADMAP_PATH=".planning/ROADMAP.md"
+REQUIREMENTS_PATH=".planning/REQUIREMENTS.md"
+```
+
+**Always available:**
+```
+PROJECT_PATH=".planning/PROJECT.md"
+STATE_PATH=".planning/STATE.md"
+```
+
+Read all files that exist. Missing files are fine — the summary adapts.
+
+## Step 3: Discover Phase Artifacts
+
+For each phase directory in `.planning/phases/`:
+
+```bash
+ls .planning/phases/*/
+```
+
+For each phase, read:
+- CONTEXT.md — what was decided
+- SUMMARY.md files — what was built
+- VERIFICATION.md — quality status
+- UAT.md — test results
+- LEARNINGS.md — extracted learnings (if exists)
+- SECURITY.md — security status (if exists)
+
+## Step 4: Generate Summary
+
+Write `.planning/MILESTONE-SUMMARY-v{VERSION}.md`:
+
+```markdown
+# Milestone {VERSION}: {Name} — Summary
+
+**Generated:** [date]
+**Status:** [complete / in-progress]
+
+---
+
+## Project Overview
+
+[From PROJECT.md — 3-5 sentences describing what the project is and why it exists]
+
+## Milestone Goal
+
+[From ROADMAP.md — what this milestone set out to deliver]
+
+## What Was Built
+
+### Phase 1: [Name]
+**Goal:** [from ROADMAP.md]
+**Status:** [complete/partial]
+**Key deliverables:**
+- [from SUMMARY.md files — what was actually built]
+
+**Decisions made:**
+- [from CONTEXT.md — key implementation choices]
+
+### Phase 2: [Name]
+[...]
+
+## Architecture
+
+[Synthesized from AGENTS.md project structure, phase summaries, and any ARCHITECTURE.md]
+
+## Key Decisions
+
+[Aggregated from DECISIONS.md and phase CONTEXT.md files — the top 5-10 decisions that shaped the project]
+
+## Lessons Learned
+
+[Aggregated from LEARNINGS.md files if they exist, or synthesized from SUMMARYs]
+
+## Current State
+
+- **Last phase completed:** [N]
+- **Open items:** [from STATE.md blockers]
+- **Test status:** [from UAT/VERIFICATION files]
+- **Security status:** [from SECURITY files if they exist]
+
+## How to Get Started
+
+[Practical instructions: how to clone, install deps, run the dev server, run tests]
+
+---
+
+*Generated by learnship milestone-summary*
+```
+
+## Step 5: Commit and Present
+
+```bash
+git add ".planning/MILESTONE-SUMMARY-v${VERSION}.md"
+git commit -m "docs: milestone ${VERSION} summary"
+```
+
+```
+learnship > MILESTONE SUMMARY COMPLETE
+
+Milestone {VERSION}: {Name}
+Phases covered: [N]
+Decisions documented: [N]
+Lessons captured: [N]
+
+Report: .planning/MILESTONE-SUMMARY-v{VERSION}.md
+
+Share this with new team members or stakeholders for a complete project overview.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Summarizing a milestone is a natural point for comprehensive reflection:
+>
+> `@agentic-learning reflect` — What was the most significant thing you learned across this entire milestone? What would you do differently if starting over? Milestone-level reflection reveals patterns invisible at the phase level.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` for milestone-level learning consolidation."*