---
name: problems-and-context-worth-scaling
description: Uncover real human problems with the 5 Whys, filter feature bloat with the Kano Model, match each problem to the right technical layer (deterministic code, classical ML, or multi-turn agents), curate dual-plane context (runtime token budgets and coding-agent harnesses), and gate releases with evaluations before scaling. Use whenever scoping a feature, writing a spec, designing an AI agent, structuring CLAUDE.md or SKILL.md files, or deciding what not to build.
---
# Problems and Context Worth Scaling

Cloud primitives and coding agents have dropped the cost of generating first-draft code near zero, which makes building and scaling the wrong thing dangerously fast. Use this self-contained five-step workflow to peel back surface feature requests into real human tension, match the problem to the simplest technical substrate that solves it, engineer tight context budgets where AI truly belongs, and verify behavior before committing production infrastructure.

## When to Use

- Turning a stakeholder request, customer complaint, or product bet into a crisp spec or prototype
- Deciding whether a problem belongs in deterministic code, classical ML ranking, or an LLM agent
- Designing runtime agent state (`Write`, `Select`, `Compress`, `Isolate`), tool contracts, and prompt caching
- Structuring repository context (`CLAUDE.md`, `AGENTS.md`, `SKILL.md`, and deterministic hooks) for coding agents
- Defining behavioral checks and evaluation gates before scaling prototypes into production systems

## Core Workflow

### Step 1: Step Out of Solution Space with the 5 Whys

Customers and stakeholders naturally ask for solutions ("add a chatbot", "add an export button"). Step back across the line from the **Solution Space** into the **Problem Space** and run **3 to 5 Whys** until you hit real human stakes:

- **Surface ask (Solution Space):** "Add an AI assistant to summarize weekly account changes."
- **Why 1?** "Because account owners spend Thursday night pulling five tabs into a doc."
- **Why 2?** "Because silent usage drops hide inside raw event tables."
- **Why 3?** "Because walking into Friday's renewal review blindsided costs trust and revenue."
- **Underlying job (Problem Space):** Knowing which accounts quietly drifted before Friday's review, with zero manual tab-stitching.

Check four situational anchors before moving forward:

1. **Physical and mental context:** Are they comparing options on a couch at 10 PM, rushing between meetings on a phone, or standing offline in glare on a highway shoulder?
2. **Existing ugly workaround:** Look for spreadsheets, screenshots, sticky notes, or group texts. Zero workaround usually signals low urgency.
3. **Importance vs. current satisfaction:** Prioritize high-importance jobs where existing options frustrate or fail users.
4. **Two audiences behind one screen:** Check whether novices need one calm action on the surface while power users need deeper controls tucked cleanly underneath.

### Step 2: Filter Feature Bloat on the Kano Curve

Because agents can generate ten passable features in an afternoon, restraint is half the craft. Map every candidate capability across three curves and cut anything sitting in the indifferent middle:

| Kano Tier | What It Means in Practice | Engineering Rule |
| :--- | :--- | :--- |
| **Must-Haves** | Baseline trust and safety; nobody applauds when they work, but breaking one causes instant churn | Lock behind deterministic code, strict auth/session isolation, or zero-regression CI gates |
| **Performance** | Core job speed, accuracy, latency, and clarity where more is linearly better | Pick 1 to 2 axes that matter most in this situation and beat every alternative cleanly |
| **Delighters** | Unexpected human care users never thought to request on a survey | Invest cycles saved by fast prototyping into one genuine Delighter instead of ten checkboxes |

Render an explicit gate verdict before writing architecture: **`Stop / Simplify`** (solve 80% of the pain with a smarter default or clearer label), **`Prototype to Learn`** (test value and usability in days with disposable code), or **`Build to Earn`** (harden for production scale).

### Step 3: Match the Problem to the Right Computing Layer

Do not force probabilistic models onto deterministic jobs, and do not write brittle if-else parsers for messy human intent. Match each part of the workflow to the layer whose failure modes fit the human stakes:

1. **Deterministic Code & Local State (Software 1.0):** Use when physics, math, billing, permissions, or courtroom/audit traceability must be 100% repeatable, or when the user operates offline. Never put an LLM between a user and a deterministic invariant.
2. **Classical Machine Learning & Ranking (Software 2.0):** Use when scoring millions of structured candidates under strict millisecond latency budgets (such as cold-start geographic ranking, propensity scoring, or anomaly thresholds) where calibrated probabilities beat generative text.
3. **Multi-Turn Agents & Generative UI (Software 3.0):** Reserve for open-ended reasoning, messy multi-constraint synthesis, and adaptive tool orchestration where natural intent cannot be pre-scripted. Often the strongest architecture is hybrid: an LLM interprets messy intent and calls deterministic, schema-validated tools.

### Step 4: Engineer Dual-Plane Context (Treat Tokens Like Scarce RAM)

Every extra token inside a context window dilutes attention, raises latency, and increases the odds of stale or conflicting instructions. Engineer context across two planes:

#### Plane 1: Runtime Product Context (`Write · Select · Compress · Isolate`)

- **Write (Externalize Working State):** Persist plans, tallies, and user preferences outside the raw message loop in structured scratchpads or key-value stores rather than hoping the model remembers Turn 2 at Turn 30.
- **Select (Just-in-Time High-Signal Retrieval):** Pull in only the context graph nodes, lakehouse preferences, and non-overlapping tool definitions needed for the current step. If a human engineer cannot tell which of two tools to call from their descriptions, an agent will guess wrong too.
- **Compress (Prefix-Stable Compaction & Caching):** Clear heavy historical tool payloads and compact older turns while keeping the system prefix, tool schemas, and cached blocks byte-stable so prompt-cache hit rates stay high and distributed KV TTLs prevent stale pricing or cross-session state bleed.
- **Isolate (Bounded Sub-Agents & Sandboxes):** Delegate noisy multi-step lookups to scoped sub-agents with isolated context windows that return concise structured summaries rather than dumping raw logs into the coordinator.

#### Plane 2: Coding-Agent & Team Harness Context

- **Keep root `CLAUDE.md` / `AGENTS.md` under 200 lines:** Include only exact build/test commands, non-obvious architectural boundaries, and recurring gotchas the agent cannot infer by reading the repo.
- **Lazy-load procedures via `SKILL.md`:** Move specialized workflows (migrations, visual QA, release steps, copy guardrails) into on-demand skills so unrelated tasks pay zero token tax.
- **Enforce zero-exception rules deterministically:** Prompts and markdown rules are advisory. Put rules that must never fail (secret/env read blocks, typechecks, schema validation, security boundaries, formatting) into deterministic hooks, sandboxes, and CI gates.

### Step 5: Prototype to Learn, Then Gate Production with Evals

1. **Prototype to Learn (1 to 3 Days):** Put a live-data prototype in front of real hands without login walls or settings scaffolding. Watch silently where users squint, hesitate, or verify answers elsewhere.
2. **Build the Eval Gate Before Tuning Prompts:** Assemble 15 to 30 realistic, messy user scenarios (ambiguous constraints, adversarial edge cases, stale state). Pair deterministic assertions (auth boundaries, schema validity, latency, cache-prefix stability) with calibrated LLM-as-judge rubrics grounded in human-graded transcripts.
3. **Know What to Sunset:** Re-audit existing wrappers and memory layers whenever foundation models or platforms ship native capabilities. Deleting redundant scaffolding is a core builder win.

## Output Template

Before generating production code or a full specification, output a **Problem, Architecture & Context Brief**:

1. **5 Whys (Solution -> Problem Space):** Surface ask vs. the underlying human job and physical/mental moment.
2. **Kano & Restraint Verdict:** Must-Haves, primary Performance axis, optional Delighter, and verdict (`Stop / Simplify`, `Prototype to Learn`, or `Build to Earn`).
3. **Layer Match:** Which pieces belong in Deterministic Code, Classical ML, or Agentic orchestration (and why).
4. **Context & State Budget:** Runtime `Write / Select / Compress / Isolate` plan, KV/prompt-cache TTL boundaries, and non-overlapping tool contracts.
5. **Verification Gate:** The deterministic checks, visual diffs, and golden eval cases that must pass before shipping.

## Gotchas

- **Prompting your way around a state bug:** Adding `CRITICAL: ALWAYS...` in all-caps to a bloated prompt rarely fixes a failure caused by polluted context or missing deterministic hooks.
- **Breaking prompt-cache prefixes dynamically:** Injecting timestamps, per-turn user metadata, or shuffled tool lists at the top of the system prompt destroys prefix caching and spikes latency and cost.
- **Shipping prototypes straight to production:** A prototype built to learn optimizes for speed of discovery; scaling to earn requires explicit auth isolation, rate limits, PII redaction, and regression evals.
