learnship 1.9.0

package/learnship/workflows/diagnose-issues.md

@@ -0,0 +1,145 @@
+---
+description: Batch-diagnose multiple UAT issues after verify-work — groups by root cause, proposes fix plan
+---
+
+# Diagnose Issues
+
+Batch-diagnose all open UAT issues after `verify-work`. Groups issues by root cause, identifies shared fixes, and proposes a structured fix plan — more efficient than debugging issues one at a time.
+
+**Usage:** `diagnose-issues [phase]`
+
+**Run after:** `verify-work [N]` has logged issues in a UAT file.
+
+## Step 1: Load Issues
+
+Find the UAT file for the phase:
+```bash
+ls ".planning/phases/"*[N]*"/"*-UAT.md 2>/dev/null | head -1
+```
+
+If no UAT file found: stop — "Run `verify-work [N]` first to log issues."
+
+Read the UAT file. Extract all open issues (status: open).
+
+If no open issues:
+```
+No open issues in Phase [N] UAT. All issues are resolved or deferred.
+```
+Stop.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DIAGNOSE ISSUES — Phase [N]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[N] open issue(s) to diagnose:
+[list of issue titles and severities]
+```
+
+## Step 2: Read Phase Context
+
+Read all PLAN.md and SUMMARY.md files for the phase to understand what was built and how:
+```bash
+cat ".planning/phases/[phase-dir]/"*-PLAN.md
+cat ".planning/phases/[phase-dir]/"*-SUMMARY.md
+```
+
+Also read `.planning/DECISIONS.md` if it exists — prior decisions often explain why an issue occurred.
+
+## Step 3: Diagnose Each Issue
+
+For each open issue, using `@./agents/debugger.md` in diagnosis mode (read-only — no implementation changes):
+
+1. **Trace the symptom** — follow the user-reported behavior inward through the codebase
+2. **Find the divergence point** — the specific file:line where behavior diverges from expected
+3. **Classify root cause:**
+   - `implementation_bug` — code exists but is wrong
+   - `missing_implementation` — code simply wasn't written
+   - `integration_gap` — two components don't connect properly
+   - `requirements_mismatch` — built correctly but wrong spec
+   - `environment` — works in code but breaks in specific environment
+
+Record for each issue:
+```
+Issue: [title]
+Root cause type: [type]
+Location: [file:line]
+Cause: [one sentence]
+Confidence: high | medium | low
+```
+
+## Step 4: Group by Root Cause
+
+Look for shared root causes across issues — frequently multiple UAT issues trace back to the same source:
+
+```
+Root Cause Groups:
+
+Group A: [common cause] → affects issues: [1, 3, 5]
+  One fix here resolves all three.
+
+Group B: [cause] → affects issue: [2]
+  Standalone fix needed.
+
+Group C: [cause] → affects issues: [4, 6]
+  Shared component needs updating.
+```
+
+## Step 5: Propose Fix Plan
+
+For each group, propose a minimal fix approach:
+
+```
+Proposed Fix Plan
+
+**Fix 1: [group A description]**
+Closes: Issues [1, 3, 5]
+Approach: [1-2 sentences]
+Files: [list]
+Effort: small | medium | large
+
+**Fix 2: [group B description]**
+Closes: Issue [2]
+Approach: [1-2 sentences]
+Files: [list]
+Effort: small | medium | large
+```
+
+Ask: "Does this diagnosis look right? Proceed with creating fix plans?"
+
+## Step 6: Create Fix Plans
+
+For each fix group, write a PLAN.md in the phase directory:
+
+```bash
+ls ".planning/phases/[phase-dir]/"*-PLAN.md | wc -l
+# Next plan ID = existing count + 1
+```
+
+Write `[padded_phase]-[next-id]-FIX-PLAN.md` using the standard plan template format.
+
+Update the UAT file — for each issue being addressed, add:
+```yaml
+fix_plan: [padded_phase]-[plan-id]-FIX-PLAN.md
+```
+
+## Step 7: Commit and Report
+
+```bash
+git add ".planning/phases/[phase-dir]/"
+git commit -m "docs([padded_phase]): add fix plans for [N] UAT issues"
+```
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DIAGNOSIS COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Issues diagnosed: [N]
+Root cause groups: [M]
+Fix plans created: [K]
+
+▶ Next: execute-plan [phase] [plan-id]  (for each fix plan)
+        or: execute-phase [phase]  (runs all remaining plans including fixes)
+```

package/learnship/workflows/discovery-phase.md

@@ -0,0 +1,183 @@
+---
+description: Structured codebase discovery before working on an unfamiliar area — reads code, maps dependencies, surfaces risks
+---
+
+# Discovery Phase
+
+Structured discovery for working on an unfamiliar part of the codebase. Maps the relevant code area, traces dependencies, identifies risks, and produces a focused discovery report before planning starts.
+
+**Usage:** `discovery-phase [N]` or `discovery-phase [area description]`
+
+**Run before:** `discuss-phase [N]` or `plan-phase [N]` when the area is unfamiliar.
+
+## Step 1: Identify Discovery Target
+
+If a phase number was provided, read the phase goal from ROADMAP.md:
+```bash
+cat .planning/ROADMAP.md | grep -A 10 "Phase [N]:"
+```
+
+If a description was provided, use it directly.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DISCOVERY — [target area]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 2: Locate Relevant Code
+
+Search for code related to the target area using key terms from the phase goal:
+
+```bash
+# Find files mentioning key terms
+grep -rl "[key term 1]" src/ 2>/dev/null | head -15
+grep -rl "[key term 2]" src/ 2>/dev/null | head -10
+
+# Find related directories
+find src/ -type d | grep -i "[key term]" 2>/dev/null
+
+# Find entry points
+grep -rn "export\|module.exports\|def " src/ --include="*.ts" --include="*.js" --include="*.py" 2>/dev/null | grep -i "[key term]" | head -20
+```
+
+Read the 5-8 most relevant files. Focus on interfaces, types, exports, and public API — not implementation details.
+
+## Step 3: Map Dependencies
+
+For the relevant files, trace what they depend on and what depends on them:
+
+**Incoming dependencies** (who calls this code):
+```bash
+grep -rl "import.*[module name]\|require.*[module name]" src/ 2>/dev/null | head -10
+```
+
+**Outgoing dependencies** (what this code calls):
+Read import statements from the relevant files.
+
+Build a dependency map:
+```
+[target area]
+  ← used by: [file A], [file B]
+  → uses: [lib X], [module Y], [service Z]
+  ↔ shares state with: [store/context/DB table]
+```
+
+## Step 4: Identify Integration Points
+
+Find where new code for this phase would need to connect:
+- Entry points (routes, event handlers, CLI commands)
+- Shared state (stores, contexts, DB models)
+- External service calls that affect this area
+- Configuration that controls behavior
+
+## Step 5: Surface Risks
+
+Look specifically for:
+
+**Complexity hotspots:**
+```bash
+# Files with most lines of code in the area
+wc -l $(find src/ -name "*.ts" -o -name "*.py" 2>/dev/null | xargs grep -l "[key term]" 2>/dev/null) | sort -n | tail -10
+```
+
+**Test coverage gaps:**
+```bash
+find . -name "*.test.*" -o -name "test_*.py" | xargs grep -l "[key term]" 2>/dev/null
+```
+
+**TODO/FIXME in the area:**
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX" src/ 2>/dev/null | grep -i "[key term]" | head -10
+```
+
+**Known issues from DECISIONS.md:**
+```bash
+grep -i "[key term]" .planning/DECISIONS.md 2>/dev/null
+```
+
+## Step 6: Write Discovery Report
+
+Write `.planning/phases/[padded_phase]-[slug]/[padded_phase]-DISCOVERY.md`:
+
+```markdown
+---
+phase: [N]
+area: [target area]
+created: [date]
+---
+
+# Discovery: [target area]
+
+## Relevant Files
+
+| File | Role | Lines |
+|------|------|-------|
+| [path] | [what it does] | [N] |
+
+## Dependency Map
+
+[ASCII diagram or bullet list]
+
+## Integration Points
+
+- **Entry point:** [where new code connects]
+- **Shared state:** [what is shared]
+- **External dependencies:** [services, APIs]
+
+## Risks
+
+### High
+- [risk]: [why it's risky, what to watch for]
+
+### Medium
+- [risk]: [description]
+
+### Low / Acceptable
+- [risk]: [description]
+
+## Test Coverage
+
+[Summary of what's tested, what's not]
+
+## Recommendations
+
+Before planning Phase [N]:
+- [Specific recommendation 1]
+- [Specific recommendation 2]
+```
+
+## Step 7: Commit and Report
+
+```bash
+git add ".planning/phases/[padded_phase]-[slug]/"
+git commit -m "docs([padded_phase]): discovery report for [area]"
+```
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DISCOVERY COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Area: [target]
+Files mapped: [N]
+Risks found: [high: N, medium: M, low: K]
+
+▶ Next: discuss-phase [N] — your decisions will be informed by this discovery
+        or: plan-phase [N] — discovery is available for the planner to read
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** Discovery complete. Verify your mental model before building:
+>
+> `@agentic-learning explain [area name]` — Explain the area you just discovered back in your own words. Gaps in the explanation are gaps in the understanding — better to find them now.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning explain [area]` to verify your understanding before planning."*

package/learnship/workflows/discuss-milestone.md

@@ -0,0 +1,136 @@
+---
+description: Capture milestone-level goals, constraints, and anti-goals before new-milestone starts
+---
+
+# Discuss Milestone
+
+Capture what the next milestone should achieve — and what it should explicitly *not* do — before committing to a roadmap. Produces a `MILESTONE-CONTEXT.md` that `new-milestone` reads to skip re-asking.
+
+**Usage:** `discuss-milestone [version]` — e.g., `discuss-milestone v2.0`
+
+**Run before:** `new-milestone`
+
+## Step 1: Load Prior Context
+
+Read what has already shipped:
+```bash
+cat .planning/PROJECT.md
+cat .planning/STATE.md
+ls .planning/milestones/ 2>/dev/null | sort -V | tail -3
+```
+
+Display the last milestone summary so the conversation starts informed:
+```
+Last shipped: [VERSION] — [Name]
+[2-sentence summary from milestones archive]
+
+Pending todos: [N] items
+```
+
+Check if a MILESTONE-CONTEXT.md already exists:
+```bash
+test -f .planning/MILESTONE-CONTEXT.md && echo "EXISTS"
+```
+
+If exists: ask "A milestone context file already exists from a prior discussion. Update it or start fresh?"
+
+## Step 2: Discuss Goals
+
+Ask openly: **"What do you want this milestone to achieve?"**
+
+Follow the thread. Dig into:
+- What user capability will exist after this milestone that doesn't exist now?
+- What's the single most important thing to ship?
+- Are there any dependencies on external things (APIs, other teams, timing)?
+- Is there a deadline or forcing function?
+
+## Step 3: Capture Anti-Goals
+
+These are often the most valuable thing to capture explicitly:
+
+Ask: **"What should this milestone explicitly NOT do?"**
+
+Examples that reveal useful constraints:
+- "Don't touch the auth system — it's in use by paying customers"
+- "Don't add real-time features — that's v3"
+- "Don't change the public API shape — clients depend on it"
+
+If the user doesn't have strong anti-goals, prompt: "Any areas of the codebase that should be off-limits? Features that feel like scope creep for this cycle?"
+
+## Step 4: Capture Constraints
+
+Ask about practical constraints:
+- **Team/time**: Solo? Team of N? Approximate timeline?
+- **Quality bar**: Prototype/spike, or production-grade?
+- **Known technical debt**: Anything that must be addressed in this milestone?
+- **Architecture decisions already made**: Anything that constrains the approach?
+
+## Step 5: Write MILESTONE-CONTEXT.md
+
+Write `.planning/MILESTONE-CONTEXT.md`:
+
+```markdown
+---
+version: [VERSION]
+created: [date]
+status: ready
+---
+
+# Milestone Context: [VERSION]
+
+## Goals
+
+[2-4 bullet points — what the user wants to achieve]
+
+## Must-Have Features
+
+[List of features/capabilities that define this milestone's success]
+
+## Anti-Goals
+
+[What this milestone explicitly does NOT include — equally important as goals]
+
+## Constraints
+
+- **Scope**: [Solo/Team, timeline if known]
+- **Quality bar**: [prototype | production-grade]
+- **Off-limits areas**: [parts of codebase not to touch]
+- **Architecture constraints**: [decisions already locked in]
+
+## Open Questions
+
+[Anything unresolved that new-milestone should ask about]
+```
+
+## Step 6: Commit and Confirm
+
+```bash
+git add .planning/MILESTONE-CONTEXT.md
+git commit -m "docs: capture milestone [VERSION] context"
+```
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► MILESTONE CONTEXT CAPTURED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Milestone: [VERSION]
+Goals: [N] captured
+Anti-goals: [N] captured
+
+▶ Next: new-milestone [VERSION]  (will read this context automatically)
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** About to start a new milestone. Brainstorm the design before locking scope:
+>
+> `@agentic-learning brainstorm [milestone topic]` — Talk through the new capabilities before committing. What's the mental model? What are the 2-3 ways this could be built? Surface blind spots now, not mid-execution.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning brainstorm [topic]` before new-milestone to surface approach alternatives."*

package/learnship/workflows/discuss-phase.md

@@ -0,0 +1,244 @@
+---
+description: Capture implementation decisions for a phase before planning starts
+---
+
+# Discuss Phase
+
+Extract implementation decisions that downstream planning needs. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.
+
+**Usage:** Run `discuss-phase [N]` before `plan-phase [N]`.
+
+**You are a thinking partner, not an interviewer.** The user is the visionary — you are the builder. Capture decisions that will guide research and planning.
+
+## Step 1: Load Phase
+
+Read `.planning/ROADMAP.md` and find the requested phase number. If not found, stop and show available phases.
+
+Read prior context to avoid re-asking decided questions:
+```bash
+cat .planning/PROJECT.md
+cat .planning/REQUIREMENTS.md
+cat .planning/STATE.md
+find .planning/phases -name "*-CONTEXT.md" 2>/dev/null | sort
+```
+
+Extract from prior CONTEXT.md files: locked preferences, patterns the user has established (e.g., "user consistently prefers minimal UI", "user rejected single-key shortcuts").
+
+## Step 1b: Load Decisions Register
+
+If `.planning/DECISIONS.md` exists, read it:
+```bash
+cat .planning/DECISIONS.md 2>/dev/null | head -80
+```
+
+Note any decisions that constrain or inform this phase's approach. Surface them during discussion rather than re-asking decided questions.
+
+## Step 2: Check Existing Context
+
+```bash
+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 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**
+
+## Step 3: Scout Codebase
+
+Do a lightweight scan to inform the discussion. Look for:
+- Existing components, hooks, utilities relevant to this phase
+- Established patterns (state management, styling, data fetching)
+- Integration points where new code would connect
+
+```bash
+ls src/components/ src/hooks/ src/lib/ src/utils/ 2>/dev/null
+```
+
+Use grep to find files related to the phase goal's key terms. Read 3-5 most relevant files. Store findings internally — don't write to a file yet.
+
+## Step 4: Identify Gray Areas
+
+Analyze the phase goal from ROADMAP.md. A gray area is an **implementation decision the user cares about** — something that could go multiple ways and would change the result.
+
+**By domain type:**
+- Something users **SEE** → layout, density, interactions, empty states
+- Something users **CALL** → response format, errors, auth flow, versioning
+- Something users **RUN** → output format, flags, modes, error handling
+- Something users **READ** → structure, tone, depth, flow
+- Something being **ORGANIZED** → grouping criteria, naming, duplicates
+
+**Check prior decisions first** — don't re-ask what's already locked from earlier phases.
+
+Generate 3-4 **phase-specific** gray areas. Not generic categories ("UI", "UX") — concrete decisions:
+```
+Phase: "User authentication"
+→ Session handling, Error responses, Multi-device policy, Recovery flow
+
+Phase: "Post Feed"
+→ Layout style (cards vs. timeline), Loading behavior, Content metadata, Empty state
+```
+
+If no meaningful gray areas exist (pure infrastructure, all already decided), note this and skip to Step 6.
+
+## Step 5: Present Gray Areas and Discuss
+
+Display:
+```
+Phase [X]: [Name]
+Domain: [what this phase delivers]
+
+We'll clarify HOW to implement this — new capabilities belong in other phases.
+```
+
+If prior decisions apply, show them:
+```
+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"
+
+**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.
+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"
+
+**Scope guardrail:** If the user suggests a new capability, say:
+```
+"[Feature X] sounds like a new capability — that's its own phase.
+Want me to note it for the roadmap backlog?
+
+Back to [current area]..."
+```
+
+Track deferred ideas internally.
+
+## Step 6: Write CONTEXT.md
+
+Find or create the phase directory:
+```bash
+mkdir -p ".planning/phases/[padded_phase]-[phase_slug]"
+```
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md`:
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Category discussed]
+- [Decision captured]
+
+### Claude's Discretion
+[Areas where user said "you decide"]
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- [Component/hook]: [How it could be used]
+
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
+
+### Integration Points
+- [Where new code connects to existing system]
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+[Any "I want it like X" moments or specific references]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up but belong in other phases]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+*Phase: [padded_phase]-[phase_slug]*
+*Context gathered: [date]*
+```
+
+## Step 7: Commit and Confirm
+
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md"
+git commit -m "docs([padded_phase]): capture phase context"
+```
+
+Update STATE.md with session info, then commit:
+```bash
+git add .planning/STATE.md && git commit -m "docs(state): record phase [X] context session"
+```
+
+Present summary:
+```
+Created: .planning/phases/[padded_phase]-[slug]/[padded_phase]-CONTEXT.md
+
+## Decisions Captured
+
+### [Category]
+- [Key decision]
+
+[If deferred ideas:]
+## Noted for Later
+- [Deferred idea] — future phase
+
+---
+
+▶ Next Up: plan-phase [X]
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer based on where you are in the discussion:
+
+> 💡 **Learning moment:** Implementation decisions just captured. Make them stick:
+>
+> `@agentic-learning either-or` — Record the decision paths considered, the choice made, and expected consequences. Builds a searchable record of your reasoning that future phases can reference.
+>
+> `@agentic-learning brainstorm [phase topic]` — If any area felt unclear or you settled quickly, talk it through now. Better to surface a blind spot here than mid-execution.
+>
+> `@agentic-learning explain-first [phase topic]` — Explain the planned approach back in your own words. If the explanation has gaps, the CONTEXT.md probably does too.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log today's decisions as a decision journal entry."*