codymaster 4.4.5 → 4.5.2

package/skills/cm-continuity/SKILL.md

@@ -29,8 +29,25 @@ cm continuity init
 # Check current state
 cm continuity status
 
-# View captured learnings
+# View captured learnings / decisions
 cm continuity learnings
+cm continuity decisions
+
+# ── Smart Spine v5 commands ──────────────────────────────
+# Regenerate L0 compact indexes (learnings-index.md, skeleton-index.md)
+cm continuity index
+
+# Show token budget allocation + usage per category
+cm continuity budget
+
+# Pretty-print current context bus state (active skill chain)
+cm continuity bus
+
+# Print Claude Desktop MCP config snippet for cm-context server
+cm continuity mcp
+
+# Migrate learnings.json + decisions.json → SQLite (one-time)
+cm continuity migrate
 ```
 
 ## The Protocol
@@ -130,45 +147,84 @@ Project: [project name]
 - [file path]: [what we're changing]
 ```
 
-## 4-Tier Memory System (Brain-Inspired)
+## Memory Architecture (v5 — Smart Spine)
 
 ```
 Tier 1: SENSORY MEMORY (seconds — within current tool call)
   → Internal variables, intermediate results
   → NEVER written to file — discarded when action completes
-  → Example: "File X has 200 lines" — no need to remember next session
 
 Tier 2: WORKING MEMORY (current session → 7 days)
-  → CONTINUITY.md — the active scratchpad
+  → CONTINUITY.md — the active scratchpad (max 500 words / ~400 tokens)
   → Auto-rotates: entries > 7 days promote to Tier 3 or decay
-  → Max 500 words (~400 tokens)
-  
-Tier 3: LONG-TERM MEMORY (30+ days, only if reinforced)
-  → .cm/learnings.json — error patterns with TTL + scope
-  → .cm/decisions.json — architecture decisions with supersedence
-  → Entries MUST be reinforced (same pattern ≥ 2x) to survive
-  → Decay: auto-archive if not relevant after TTL expires
+  → Context bus (.cm/context-bus.json) — live skill chain state
+    · initBus() on chain start, updateBusStep() on each advance
+    · cm://pipeline/current resolves to bus JSON
+    · Read via: cm continuity bus | cm_bus_read MCP tool
 
-Tier 4: EXTERNAL SEMANTIC MEMORY (optional — for large projects)
+Tier 3: LONG-TERM MEMORY (30+ days, only if reinforced)
+  → Primary:  .cm/context.db (SQLite + FTS5) ← v5 default
+      · learnings table + learnings_fts (BM25 keyword search)
+      · decisions table + decisions_fts
+      · skill_outputs per session/chain
+      · indexes table (cached L0/L1 content + staleness hash)
+  → Fallback: .cm/memory/learnings.json + decisions.json (kept for compat)
+  → L0 indexes: .cm/learnings-index.md (~100 tok), .cm/skeleton-index.md (~500 tok)
+      · Auto-regenerated on addLearning() + on demand via cm continuity index
+      · File watcher auto-refreshes learnings L0 on JSON change (300ms debounce)
+  → Token budget: .cm/token-budget.json — 200k window, per-category soft limits
+      · Enforced at load time: checkBudget() → allowed/remaining/suggestion
+      · View: cm continuity budget
+
+Tier 4: EXTERNAL SEMANTIC MEMORY (optional — large projects)
   → tobi/qmd — BM25 + Vector + LLM re-ranking, 100% local
-  → Indexes entire docs/, src/, meeting notes folders
-  → AI queries via MCP: qmd query "keyword" → relevant snippets
-  → See cm-deep-search skill for setup & detection thresholds
-  → ONLY suggested when project >50 docs or >200 source files
+  → See cm-deep-search skill — ONLY when >50 docs or >200 source files
 
-Tier 5: STRUCTURAL CODE MEMORY (optional — for code-heavy projects)
+Tier 5: STRUCTURAL CODE MEMORY (optional — code-heavy projects)
   → CodeGraph — tree-sitter AST → SQLite graph → MCP server
-  → Indexes symbols, call graphs, imports, class hierarchies
-  → AI queries: codegraph_context, codegraph_impact, codegraph_callers
-  → See cm-codeintell skill for setup & integration
-  → ONLY suggested when project >50 source files
+  → See cm-codeintell skill — ONLY when >50 source files
 ```
 
-**CONTINUITY.md = "what am I doing NOW?"**
-**learnings.json = "what mistakes should I avoid?"**  
-**decisions.json = "what architecture rules apply?"**
+**CONTINUITY.md  = "what am I doing NOW?"**
+**context bus    = "what did upstream skills produce in this chain?"**
+**L0 indexes     = "cheapest possible memory load (~600 tokens)"**
+**context.db     = "keyword search across all learnings + decisions"**
 **qmd (optional) = "find what was written across hundreds of docs"**
 
+### MCP Context Server (Claude Desktop integration)
+
+Seven tools exposed over stdio to Claude Desktop and MCP-compatible clients:
+
+| Tool | Purpose |
+|---|---|
+| `cm_query` | FTS5 keyword search — learnings, decisions, or both |
+| `cm_resolve` | Load any `cm://` URI at L0/L1/L2 depth |
+| `cm_bus_read` | Read live context bus state |
+| `cm_bus_write` | Publish skill output to the bus |
+| `cm_budget_check` | Pre-flight token check by category |
+| `cm_memory_decay` | Archive expired learnings (supports dry_run) |
+| `cm_index_refresh` | Regenerate L0 indexes on demand |
+
+```bash
+# Get install snippet for Claude Desktop config
+cm continuity mcp
+```
+
+### cm:// URI Scheme
+
+Reference any memory resource by URI — resolver handles depth + caching:
+
+```
+cm://memory/working              → CONTINUITY.md
+cm://memory/learnings            → learnings-index.md (L0) or SQLite (L1/L2)
+cm://memory/learnings/{id}       → specific learning by ID
+cm://memory/decisions            → decisions index
+cm://skills/{name}               → SKILL.md at depth
+cm://skills/{name}/L0            → front matter + description only (~50 tokens)
+cm://resources/skeleton          → skeleton-index.md (L0) or full
+cm://pipeline/current            → live context bus state
+```
+
 ---
 
 ## Memory Audit Protocol (Auto — Every Session Start)
@@ -383,22 +439,28 @@ WHY: Smaller scope = less noise = AI only reads what's relevant.
 
 ```
 ✅ DO:
-- Read CONTINUITY.md at session start (ALWAYS)
+- Check context bus FIRST at session start (free, ~50 tokens)
+- Load L0 indexes BEFORE full files (learnings-index + skeleton-index)
+- Use cm_query for keyword search — don't scan JSON manually
+- Read CONTINUITY.md after L0 indexes (not before)
 - Run Memory Audit at session start (decay + conflicts + scope filter)
 - Update CONTINUITY.md at session end (ALWAYS)
 - Tag EVERY learning/decision with scope (global/module/file)
 - Reinforce existing learnings instead of creating duplicates
 - Keep CONTINUITY.md under 500 words (rotate to Tier 3)
 - Be specific: "Fixed auth bug in login.ts:42" not "Fixed stuff"
+- Run cm continuity index after bulk learning additions
 
 ❌ DON'T:
+- Load full learnings.json or skeleton.md as first action (use L0 first)
+- Skip context bus check when inside a skill chain
 - Skip Memory Audit ("I'll read everything, it's fine")
 - Write learnings without scope ("it applies everywhere" = almost never true)
 - Create duplicate learnings (reinforce existing ones instead)
-- Let learnings.json grow unbounded (TTL + decay handles this)
-- Read ALL learnings regardless of current module (use scope filter)
+- Let learnings.json grow unbounded (TTL + decay + cm_memory_decay handles this)
+- Read ALL learnings regardless of current module (use scope filter / cm_query)
 - Ignore superseded decisions (they cause conflicting code)
-- Keep stale context that no longer applies to current architecture
+- Inject skeleton.md (20KB) when skeleton-index.md (~2KB) is sufficient
 ```
 
 ## The Bottom Line

package/skills/cm-skill-chain/SKILL.md

@@ -65,6 +65,47 @@ Full skill names: `cm-brainstorm-idea`, `cm-planning`, `cm-tdd`, `cm-execution`,
 - **cm-continuity**: Chain progress persists across sessions via CONTINUITY.md working memory
 - **cm-execution**: Each chain step delegates to cm-execution for actual implementation
 - **cm-quality-gate**: Automatically runs at end of each development chain
+- **Context Bus (v5)**: Every chain automatically maintains `.cm/context-bus.json` — shared state across all steps
+
+## Context Bus — Inter-Skill Coordination (v5)
+
+When `chain start` runs, the context bus is initialized automatically:
+
+```
+chain start feature-development "add payment flow"
+→ Creates .cm/context-bus.json with:
+    pipeline: "feature-development"
+    session_id: "<uuid>"
+    current_step: "brainstorm-idea"
+    shared_context: {}
+    resource_state: { skeleton_generated: null, learnings_indexed: null, ... }
+```
+
+When `chain advance` runs after each skill completes:
+
+```
+chain advance <exec-id> "summary of what was done"
+→ Updates context-bus.json:
+    current_step: "planning"   ← moved forward
+    shared_context.brainstorm-idea: { summary, affected_files, output_path }
+```
+
+**What downstream skills gain:**
+- `cm-planning` can read brainstorm output path → no re-read of full filesystem
+- `cm-tdd` can see which files planning created → targeted test generation
+- `cm-quality-gate` knows exactly which files changed → focused review
+
+**Reading the bus:**
+```bash
+cm continuity bus          # terminal pretty-print
+cm_bus_read                # MCP tool (Claude Desktop)
+cm://pipeline/current      # URI resolver (in skill prompts)
+```
+
+**Publishing to the bus (inside a skill):**
+```bash
+cm_bus_write skill=cm-planning summary="tasks.md created" output_path=openspec/...
+```
 
 ## For AI Agents
 
@@ -74,5 +115,10 @@ When dispatching tasks that match a chain pattern:
 1. Check if task matches a chain: suggestChain(taskTitle)
 2. If match found, suggest to user: "This task matches the X chain pipeline"
 3. If user agrees, start the chain and invoke skills in order
-4. After completing each skill, advance the chain
+4. At the START of each skill step:
+   → Read cm://pipeline/current to see upstream skill outputs
+   → Check shared_context to avoid re-doing work
+5. After completing each skill, advance the chain:
+   → chain advance <id> "summary"
+   → This updates context bus + CONTINUITY.md simultaneously
 ```

package/skills/cm-start/SKILL.md

@@ -10,8 +10,15 @@ description: Start the CM Workflow to execute your objective from idea to produc
 When this workflow is called, the AI Assistant should execute the following action sequence in the spirit of the **CodyMaster Kit**:
 
 0. **Load Working Memory:**
-    Per `_shared/helpers.md#Load-Working-Memory`
-    - Update `CONTINUITY.md` → set Active Goal to the new objective
+    Per `_shared/helpers.md#Load-Working-Memory` — **use Smart Spine order:**
+    1. Check `.cm/context-bus.json` → any active pipeline? any prior skill output to reuse?
+    2. Load L0 indexes: `learnings-index.md` (~100 tok) + `skeleton-index.md` (~500 tok)
+    3. Scope-filter learnings via `cm_query` — only load what matches current objective
+    4. Read `CONTINUITY.md` → set Active Goal to the new objective
+    5. Run token budget check: `cm continuity budget` → confirm no category is over soft limit
+
+    > ⚡ Total context load: ~700 tokens. Full load used to be ~3,200.
+    > Only escalate to L2 (full files) if L0 index explicitly flags a match.
 
 0.5. **Skill Coverage Check (Adaptive Discovery):**
     - Scan the objective for technologies, frameworks, or patterns mentioned
@@ -73,5 +80,7 @@ When this workflow is called, the AI Assistant should execute the following acti
 4. **Complete:**
     Per `_shared/helpers.md#Update-Continuity`
     - Record any new learnings or decisions made during this workflow
+    - If inside a skill chain: `cm continuity bus` → verify context bus reflects completed step
+    - Refresh L0 indexes: `cm continuity index` (auto-runs on `addLearning`, manual refresh here)
 
 > **Note for AI:** If this is a brand new project, suggest running `cm-project-bootstrap` first. If the working environment has a risk of accidentally switching accounts/projects, remind about `cm-identity-guard` (Per `_shared/helpers.md#Identity-Check`).

package/skills/boxme-git-config/SKILL.md

@@ -1,56 +0,0 @@
----
-description: Verify and fix git configuration to ensure all pushes go to omisocial GitHub account
----
-
-# Git Account Verification
-
-Use this skill when: "check git", "verify git", "git account", "fix remote", "push fails", or before any deploy/push operation.
-
-## Expected Configuration
-
-| Setting | Expected Value |
-|---------|---------------|
-| `gh auth status` | `omisocial` |
-| `git remote origin` | `https://github.com/omisocial/boxme_levelling.git` |
-| `git config user.name` | `omisocial` |
-| `git config user.email` | `omisocial@users.noreply.github.com` |
-
-## Quick Check
-
-Run this one-liner to verify everything:
-
-```bash
-echo "=== GitHub CLI ===" && gh auth status 2>&1 | head -3 && echo "=== Git Remote ===" && git remote get-url origin && echo "=== Git User ===" && git config user.name && git config user.email
-```
-
-## Fix if Wrong
-
-### GitHub CLI (gh) logged into wrong account
-```bash
-gh auth logout
-gh auth login
-# Select: Login with web browser → omisocial
-```
-
-### Git remote pointing to wrong repo
-```bash
-git remote set-url origin https://github.com/omisocial/boxme_levelling.git
-```
-
-### Git user config wrong
-```bash
-git config user.name "omisocial"
-git config user.email "omisocial@users.noreply.github.com"
-```
-
-## Project Root
-```
-/Users/todyle/Library/Mobile Documents/com~apple~CloudDocs/Code/Boxme_Projects/boxme_levelling-main
-```
-
-## Account History
-
-| Account | Purpose | Status |
-|---------|---------|--------|
-| `omisocial` | Current active GitHub account | ✅ Active |
-| `boxmevibe` | Previous GitHub account | ⚠️ Archived as `old-boxmevibe` remote |

package/skills/boxme-local-dev/SKILL.md

@@ -1,66 +0,0 @@
----
-description: Start all Boxme Scoring System local development modules (PRMS, Seller SOS, Docs Site)
----
-
-# Boxme Local Dev — Start All Modules
-
-Use this skill when the user says any of: "start local", "run local", "dev local", "start dev", or asks to run the Boxme project locally.
-
-## Project Root
-
-```
-/Users/todyle/Library/Mobile Documents/com~apple~CloudDocs/Code/Boxme_Projects/boxme_levelling-main
-```
-
-## Modules
-
-| Module | Directory | Command | URL |
-|--------|-----------|---------|-----|
-| **PRMS** (Performance Review) | project root | `npm run dev` | http://localhost:5173 |
-| **Seller SOS** | `seller-sos/` | `npm run dev` | http://localhost:5174 |
-| **Docs Site** (Docusaurus) | `docs-site/` | `npm start` | http://localhost:3000 |
-
-## Instructions
-
-### Step 1 – Start PRMS
-
-Open terminal and run:
-
-```bash
-cd "/Users/todyle/Library/Mobile Documents/com~apple~CloudDocs/Code/Boxme_Projects/boxme_levelling-main"
-npm run dev
-```
-
-### Step 2 – Start Seller SOS
-
-Open a **new terminal** and run:
-
-```bash
-cd "/Users/todyle/Library/Mobile Documents/com~apple~CloudDocs/Code/Boxme_Projects/boxme_levelling-main/seller-sos"
-npm run dev
-```
-
-### Step 3 – Start Docs Site
-
-Open another **new terminal** and run:
-
-```bash
-cd "/Users/todyle/Library/Mobile Documents/com~apple~CloudDocs/Code/Boxme_Projects/boxme_levelling-main/docs-site"
-npm start
-```
-
-## Notes
-
-- PRMS uses **Vite + Hono** (Cloudflare Workers backend), served via `@hono/vite-dev-server`
-- Seller SOS also uses **Vite + Hono**, port 5174
-- Docs Site is **Docusaurus 3.x**, starts on port 3000
-- All modules use their own `node_modules` — run `npm install` in each directory if fresh clone
-- If a port is busy, kill it: `lsof -ti:5173 | xargs kill -9`
-
-## Ports Quick Reference
-
-```
-http://localhost:5173  → PRMS
-http://localhost:5174  → Seller SOS  
-http://localhost:3000  → Docs Site
-```

package/skills/jobs-to-be-done/SKILL.md

@@ -1,266 +0,0 @@
----
-name: jobs-to-be-done
-description: 'Discover what customers truly need by analyzing the "job" they hire your product to do. Use when the user mentions "customer discovery", "why customers churn", "what job does this solve", "competing against luck", or "product-market fit". Covers JTBD interviews, competition analysis, and jobs-oriented roadmaps. For product positioning, see obviously-awesome. For rapid validation, see design-sprint.'
-license: MIT
-metadata:
-  author: wondelai
-  version: "1.1.1"
----
-
-# Jobs to Be Done Framework
-
-Framework for discovering innovation based on a fundamental truth: customers don't buy products - they "hire" them to do a specific job in their lives.
-
-## Core Principle
-
-**Job to Be Done** = the progress a customer wants to make in specific circumstances.
-
-Key elements of the definition:
-- **Progress** (not goal, not solution) - customer wants to move from current state to a better one
-- **Circumstances** - context determines the job, not customer attributes (demographics are useless)
-- **Hiring/Firing** - customer actively chooses a product for the "job"
-
-## Scoring
-
-**Goal: 10/10.** When reviewing or creating product strategy or positioning, rate it 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and specific improvements needed to reach 10/10.
-
-## Three Dimensions of Every Job
-
-Every job has three inseparable dimensions - omitting any means failure:
-
-| Dimension | Question | Example (milkshake) |
-|-----------|----------|---------------------|
-| **Functional** | What does the customer need to do? | Occupy myself during boring commute |
-| **Emotional** | How do they want to feel? | Have a small treat for myself |
-| **Social** | How do they want to be perceived? | As a sensible parent (not buying donuts) |
-
-## Framework
-
-### 1. The Job Statement
-
-**Core concept:** A job statement captures the progress a customer seeks in a specific circumstance, expressed in a structured format that separates context, desired progress, and expected outcome.
-
-**Why it works:** By forcing teams to articulate the job in the customer's language and circumstances, it prevents solution-first thinking and keeps innovation grounded in real human progress.
-
-**Key insights:**
-- The format is: "When [circumstances], I want to [progress], so I can [outcome]"
-- Circumstances matter more than customer demographics - the same person has different jobs in different situations
-- A well-written job statement never mentions your product or any specific solution
-- Jobs are stable over time; solutions change but the underlying job persists
-
-**Product applications:**
-
-| Context | Application | Example |
-|---------|-------------|---------|
-| New product ideation | Define the job before brainstorming features | "When I'm commuting alone, I want something to occupy me and satisfy hunger, so I'm not hungry until lunch" |
-| Feature prioritization | Evaluate whether a feature serves the core job | Prioritize features that help accomplish the stated job over nice-to-have additions |
-| Positioning & messaging | Use the job statement language in marketing copy | Lead with the circumstance and desired progress, not product specs |
-
-**Copy patterns:**
-- "When you're [circumstance], you need [progress] -- that's exactly what [product] does"
-- Lead with the situation the customer recognizes, not the product category
-- Mirror the emotional and social dimensions alongside the functional one
-
-**Ethical boundary:** Never fabricate or exaggerate circumstances to manufacture urgency. The job must reflect genuine customer progress, not artificially created anxiety.
-
-See: [references/innovation-process.md](references/innovation-process.md)
-
-### 2. Forces of Progress (Push, Pull, Anxiety, Habit)
-
-**Core concept:** The decision to "hire" a new product results from the interplay of four forces: Push (frustration with current situation), Pull (attraction of new solution), Anxiety (fear of the new), and Habit (comfort with current behavior). Change only happens when Push + Pull > Habit + Anxiety.
-
-**Why it works:** Most innovation efforts focus only on making the product better (increasing Pull), but ignore the equally powerful anti-change forces. Understanding all four forces reveals why great products still fail to gain adoption.
-
-**Key insights:**
-- Push is frustration with the current situation ("this annoys me")
-- Pull is the attraction of a new solution ("I want this")
-- Habit is attachment to current behavior ("I've always done it this way")
-- Anxiety is fear of the new ("what if it doesn't work?")
-- Often it's more effective to reduce anxiety and habit than to increase push and pull
-- Passive seekers (vaguely aware of a problem) are easier to influence than active seekers who already have criteria
-
-**Product applications:**
-
-| Context | Application | Example |
-|---------|-------------|---------|
-| Onboarding design | Reduce anxiety with free trials, guarantees, and social proof | Money-back guarantee addresses "what if it doesn't work?" anxiety |
-| Switching campaigns | Address habit directly by making migration effortless | One-click data import from competitor reduces habit friction |
-| Content marketing | Awaken push in passive seekers by naming their frustration | Blog post: "5 signs your current tool is costing you hours every week" |
-
-**Copy patterns:**
-- Address anxiety directly: "No lock-in, cancel anytime, your data is always yours"
-- Name the push: "Tired of [frustration]? There's a better way"
-- Reduce habit friction: "Switch in 5 minutes -- we import everything automatically"
-
-**Ethical boundary:** Never manufacture artificial push by exaggerating pain or creating fear. Reducing real anxiety is ethical; creating new anxiety to drive sales is manipulation.
-
-See: [references/competitive-strategy.md](references/competitive-strategy.md)
-
-### 3. The Big Hire & Little Hire
-
-**Core concept:** There are two distinct decision moments: the Big Hire (purchase/signup decision, happens once) and the Little Hire (decision to use in the moment, happens repeatedly). Winning the Big Hire does not guarantee the Little Hire.
-
-**Why it works:** Many products win the sale but lose the customer because they optimize only for the purchase decision and neglect the repeated usage decision. Understanding both moments reveals where retention problems truly originate.
-
-**Key insights:**
-- Big Hire is driven by marketing, onboarding, and first impressions
-- Little Hire is driven by product quality, UX, and ongoing value delivery
-- Many products lose at the Little Hire stage -- purchased but never used
-- The forces of progress operate differently at each stage: Big Hire anxiety is about the purchase risk; Little Hire anxiety is about effort and learning curves
-- Retention problems are almost always Little Hire failures, not Big Hire failures
-
-**Product applications:**
-
-| Context | Application | Example |
-|---------|-------------|---------|
-| Retention analysis | Distinguish Big Hire metrics from Little Hire metrics | Track "first use after signup" and "weekly active usage" separately from signup conversion |
-| Product design | Optimize the repeated usage experience, not just first impression | Reduce friction in daily workflows even if onboarding is already smooth |
-| Customer success | Monitor Little Hire signals to predict churn | Declining usage frequency is a Little Hire failure signaling upcoming churn |
-
-**Copy patterns:**
-- Big Hire copy focuses on the promise: "Transform how you [job]"
-- Little Hire copy focuses on ease: "One click and you're done"
-- Re-engagement copy addresses Little Hire failure: "We've made [specific friction] easier"
-
-**Ethical boundary:** Never design dark patterns that win the Big Hire (e.g., hidden fees, misleading trials) while failing the Little Hire. Both decisions must deliver genuine progress.
-
-See: [references/case-studies.md](references/case-studies.md)
-
-### 4. Competitive Landscape (Non-Obvious Competition)
-
-**Core concept:** True competition is everything a customer can "hire" for the same job, often from completely different product categories. Competitors are defined by the job, not by industry classification.
-
-**Why it works:** Analyzing competition through product categories creates blind spots. A milkshake competes with bananas, bagels, boredom, and podcasts. Netflix competes with TikTok, sleep, family conversation, and games. By mapping the full competitive landscape around the job, teams spot threats and opportunities invisible to traditional analysis.
-
-**Key insights:**
-- Non-consumption (doing nothing) is often the biggest competitor
-- Workarounds and compensating behaviors reveal unserved jobs: people hack, combine, and improvise solutions
-- Online courses compete with books, YouTube, mentoring, and doing nothing
-- Integration is needed when performance is "not good enough" for the job; modularization when it's "good enough"
-- The best competitive positioning answers "what job are we the best hire for?" not "how do we compare to similar products?"
-
-**Product applications:**
-
-| Context | Application | Example |
-|---------|-------------|---------|
-| Competitive analysis | Map all hires for the same job across categories | A project management tool competes with spreadsheets, sticky notes, email threads, and memory |
-| Positioning strategy | Position against the real alternative, not the obvious one | Position against "doing it manually" rather than against a named competitor |
-| Pricing strategy | Price relative to the job's value, not competitor pricing | If the job saves 10 hours per week, price against the value of that time, not against similar SaaS products |
-
-**Copy patterns:**
-- "Stop using [workaround] for [job] -- there's a purpose-built solution"
-- "You wouldn't hire a [bad fit] to [job] -- so why are you using [current hack]?"
-- Position around the job outcome, not feature comparison charts
-
-**Ethical boundary:** Never misrepresent competitors or create false equivalences. Honest competitive framing based on the job is powerful; distorting alternatives is deceptive.
-
-See: [references/competitive-strategy.md](references/competitive-strategy.md)
-
-### 5. Customer Discovery Interviews
-
-**Core concept:** Don't ask customers directly "what do you need" -- they don't know. Instead, investigate the purchase timeline by reconstructing the moments of first thought, search, purchase, and usage to uncover the real job.
-
-**Why it works:** Customers rationalize decisions after the fact and can't articulate latent needs. By walking backward through the concrete events of their decision journey, you uncover the true circumstances, forces, and tradeoffs that drove their behavior.
-
-**Key insights:**
-- First thought questions: "When did you first think about looking for a solution?", "What was happening in your life then?", "What was frustrating you?"
-- Search questions: "What alternatives did you look for?", "What eliminated options?", "Who did you talk to about this decision?"
-- Purchase moment questions: "Where were you?", "What ultimately convinced you?", "What were you afraid of?"
-- Usage questions: "Is the product doing what you expected?", "What surprised you?", "What's still missing?"
-- Signals of undiscovered jobs: workarounds, non-consumption, compensating behaviors, negative emotions with current solutions
-
-**Product applications:**
-
-| Context | Application | Example |
-|---------|-------------|---------|
-| New market entry | Interview people who recently switched to or from a competitor | Reconstruct the timeline to find what pushed them away and pulled them toward the new solution |
-| Churn reduction | Interview churned customers about their decision timeline | Discover whether the failure was Big Hire (wrong expectations) or Little Hire (poor daily experience) |
-| Feature discovery | Interview customers using workarounds | A customer using spreadsheets alongside your product reveals an unmet job dimension |
-
-**Copy patterns:**
-- Use exact customer language from interviews in marketing copy
-- "We heard you say [verbatim quote] -- so we built [feature]"
-- Frame benefits using the circumstances and emotions customers actually described
-
-**Ethical boundary:** Never lead interview subjects toward predetermined conclusions. The goal is genuine discovery, not confirmation of existing assumptions.
-
-See: [references/innovation-process.md](references/innovation-process.md)
-
-### 6. Designing for the Job
-
-**Core concept:** Build the entire product experience -- features, metrics, and organization -- around helping the customer accomplish their job, not around internal capabilities or competitive feature parity.
-
-**Why it works:** When every product decision answers "will this help the customer better accomplish their job?", teams avoid feature bloat, build coherent experiences, and create products that customers genuinely value. If you can't answer the question, you don't understand the job yet.
-
-**Key insights:**
-- Replace customer satisfaction metrics with "did the job get done?" metrics
-- Replace NPS with "reasons for hiring and firing"
-- Replace feature usage metrics with "progress on the job"
-- When the job is poorly understood, integrate (control entire experience); when well understood, modularize (specialize components)
-- Integrate where performance is "not good enough" for the job; modularize where it's "good enough"
-- Every product decision should answer: "Will this help the customer better accomplish their job?"
-
-**Product applications:**
-
-| Context | Application | Example |
-|---------|-------------|---------|
-| Metrics design | Define success metrics around job completion | Track "time from problem to resolution" instead of "features used per session" |
-| Product roadmap | Prioritize based on job dimensions (functional, emotional, social) | A functional improvement that ignores the emotional dimension may not move the needle |
-| Organizational alignment | Structure teams around jobs, not product components | A "morning commute job" team owns everything from content to packaging to distribution |
-
-**Copy patterns:**
-- "Built for [the job], not for [the category]"
-- Emphasize outcome and progress, not features and specifications
-- "Everything you need to [job] -- nothing you don't"
-
-**Ethical boundary:** Never design addictive patterns that serve engagement metrics rather than genuine customer progress. The job framework demands that the customer's progress is the true north, not your retention numbers.
-
-See: [references/organizational-change.md](references/organizational-change.md)
-
-## Common Mistakes
-
-| Mistake | Why It Fails | Fix |
-|---------|-------------|-----|
-| Defining jobs too narrowly around your product | You miss the real competitive landscape and build features no one needs | Define the job from the customer's perspective, never mentioning your product |
-| Ignoring the emotional and social dimensions | Functional-only jobs miss why customers actually choose (and stay with) products | Always complete all three dimensions: functional, emotional, and social |
-| Confusing jobs with goals or tasks | Goals are too abstract ("be healthy") and tasks are too specific ("click button") to drive strategy | Jobs describe progress in specific circumstances -- more concrete than goals, more strategic than tasks |
-| Only increasing Pull while ignoring Anxiety and Habit | A great product still fails if switching costs and fear are too high | Map all four forces and design interventions for each, especially reducing anti-change forces |
-| Winning the Big Hire but ignoring the Little Hire | High acquisition with high churn -- purchased but never used | Track and optimize the repeated usage decision separately from the purchase decision |
-| Asking customers "what do you want?" | Customers rationalize and can't articulate latent needs; you get incremental feature requests | Use timeline-based discovery interviews that reconstruct actual behavior and decisions |
-| Defining competition by product category | You miss the real threats and opportunities from adjacent categories and non-consumption | Map every alternative the customer could "hire" for the same job, including doing nothing |
-
-## Quick Diagnostic
-
-| Question | If No | Action |
-|----------|-------|--------|
-| Can you state the job in one sentence without mentioning your product? | You're product-focused, not job-focused | Write a job statement: "When [circumstances], I want to [progress], so I can [outcome]" |
-| Have you mapped all four forces (Push, Pull, Anxiety, Habit)? | You're likely over-investing in Pull and ignoring barriers | Map each force and design specific interventions for Anxiety and Habit |
-| Do you know the emotional and social dimensions of the job? | Your product may win functionally but lose on experience | Conduct discovery interviews focused on feelings and social context around the decision |
-| Have you identified non-obvious competitors from other categories? | You have blind spots in your competitive landscape | List everything a customer could "hire" for the same job, including non-consumption |
-| Are you tracking Little Hire separately from Big Hire? | You can't distinguish acquisition problems from retention problems | Create separate metrics for purchase conversion and repeated usage engagement |
-| Can your team explain how a feature helps accomplish the job? | You're building features without strategic grounding | Require every feature proposal to reference the specific job dimension it serves |
-| Have you interviewed customers about their purchase timeline? | Your understanding of the job is based on assumptions, not evidence | Conduct 10+ discovery interviews reconstructing the first-thought-to-usage journey |
-
-See: [references/diagnostics.md](references/diagnostics.md) for the full diagnostic checklist.
-
-## Examples and Case Studies
-
-See: [references/case-studies.md](references/case-studies.md) for detailed analyses (SNHU, American Girl, Intuit).
-
-## Reference Files
-
-- [innovation-process.md](references/innovation-process.md): Job hunting methodology, job atlas, prototype testing, job statements
-- [competitive-strategy.md](references/competitive-strategy.md): Non-obvious competition, jobs-based positioning, pricing strategy
-- [organizational-change.md](references/organizational-change.md): Overcoming objections, feature-factory trap, executive buy-in, change management
-- [diagnostics.md](references/diagnostics.md): Diagnostic checklist for evaluating products through the jobs lens
-- [case-studies.md](references/case-studies.md): Detailed analyses of SNHU, American Girl, Intuit, and more
-
-## About the Author
-
-Clayton M. Christensen (1952-2020) was the Kim B. Clark Professor of Business Administration at Harvard Business School and one of the most influential management thinkers of the modern era. He is best known for introducing the theory of disruptive innovation in his landmark book *The Innovator's Dilemma* (1997), which fundamentally changed how business leaders think about competition and market evolution. Christensen developed the Jobs to Be Done framework as a practical methodology for understanding customer motivation and driving successful innovation, detailed in *Competing Against Luck* (2016). He co-founded the innovation consulting firm Innosight and the Clayton Christensen Institute for Disruptive Innovation. Christensen was ranked the #1 management thinker in the world by Thinkers50 and received the award multiple times. His body of work, spanning nine books including *The Innovator's Solution* and *How Will You Measure Your Life?*, continues to shape product strategy, corporate innovation, and entrepreneurial thinking worldwide.
-
-## Further Reading
-
-This skill is based on the Jobs to Be Done framework developed by Clayton M. Christensen. For the complete methodology, case studies, and deeper insights, read the original book:
-
-- [*"Competing Against Luck: The Story of Innovation and Customer Choice"*](https://www.amazon.com/Competing-Against-Luck-Innovation-Customer/dp/0062435612?tag=wondelai00-20) by Clayton M. Christensen, Taddy Hall, Karen Dillon, and David S. Duncan