context-engineering

What this skill does

# Context Engineering for AI Products

> **ARCHIVED SKILL**
>
> This skill has been integrated into the unified spec system:
> - **New AI features:** Use `/spec --ai` or `/spec --deep context`
> - **Diagnose issues:** Use `/ai-debug`
> - **Quality checks:** Use `/context-check`
>
> This file remains as a **reference** for the full 4D Context Canvas framework.

---

## Core Philosophy

**Context engineering is the art of giving AI exactly the right information to do its job.**

Models are commodities—your context is your moat.

Most AI features fail before they reach the model. They fail because:
- Nobody defined the model's actual job
- Nobody mapped what context it needs
- Nobody figured out how to get that context at runtime
- Nobody designed what happens when it breaks

This skill prevents those failures.

## The 90/10 Mismatch

Teams spend 90% of their time on model selection and prompts.
But 90% of AI quality comes from context quality.

When AI fails, teams blame the model. But the real causes:
- System doesn't know what file the user is working on
- System doesn't see the user's preferences
- System isn't aware of entities or relationships in the workspace
- System cannot recognize the user's role
- System retrieves irrelevant documents
- System misses crucial logs or state

**Fix the context, fix the AI.**

## PM's Role in Context Engineering

Context engineering is NOT an engineering problem. It sits at the intersection of product strategy, user understanding, and system design.

**PMs own three critical layers:**

1. **Defining "intelligence"** - What should the AI know? What's essential vs nice-to-have? What level of personalization without feeling creepy?

2. **Mapping context requirements to user value** - Translating "users want better suggestions" into "system needs access to past rejections, current workspace state, and team preferences"

3. **Designing degradation strategy** - When context is missing, stale, or incomplete: Block the feature? Show partial answer? Ask clarifying questions? Fall back to non-personalized?

**Engineers own the implementation:** Retrieval architecture, vector databases, embedding pipelines, API integrations, performance optimization.

**But they need you to define the what and why before they can build the how.**

---

## Entry Point

When this skill is invoked, start with:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 CONTEXT ENGINEERING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What are you working on?

  1. Spec a new AI feature
     → Define what context it needs before engineering starts

  2. Diagnose an existing AI feature
     → Figure out why it's underperforming or hallucinating

  3. Quick quality check
     → Validate context before shipping or during review

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Route to the appropriate path based on user selection.

---

## Path 1: Spec New Feature (4D Context Canvas)

### Purpose
Walk through four dimensions that determine whether an AI feature ships successfully or dies in production. Use BEFORE engineering starts.

### Starting Point

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SPEC NEW FEATURE — 4D Context Canvas
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

We'll walk through 4 dimensions. Most AI features fail before
they reach the model—this prevents that.

How do you want to start?

  1. From a Linear issue (I'll pull the details)
  2. Describe it manually

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**If Linear:** Use Linear MCP to pull issue details. Pre-populate what's available.

**If Manual:** Ask user to describe the AI feature in 1-2 sentences.

### D1 — DEMAND: What's the Model's Job?

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 D1: DEMAND — What's the model's job?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 If you can't articulate the job precisely, the model can't do it.
   "Make it smart" is not a spec. Neither is "personalized."
```

**Questions to ask:**

1. **What should the model produce?**
   - Push for specificity: Not "recommendations" → "3 ranked options with rationale"
   - Not "a summary" → "2-paragraph executive summary with key metrics"

2. **For whom?** (User segment, role, context)

3. **Under what assumptions?** (What must be true for this to work?)

4. **What constraints apply?** (Tone, format, length, boundaries, prohibited content)

5. **What defines success?** (Measurable outcome, not "users like it")

**The transformation to model:**

```
VAGUE: "Draft a status update"

PRECISE: "Summarize the key changes in project X since the last report,
structured for stakeholder Y, using the user's preferred tone,
adhering to the product's reporting format, in under 200 words."
```

**Education moment:**
```
💡 PM vs Engineer: You own the what and why. Engineers own the how.
   Without this spec, they build impressive systems that feel hollow.
```

**Capture and display D1 summary before moving on.**

### D2 — DATA: What Context Is Required?

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 D2: DATA — What context does the model need?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Every piece of context costs tokens. More tokens = higher cost +
   slower responses. Include only what's essential for the job.
```

**Build a Context Requirements Table together:**

For each piece of context needed:

1. **Data Needed** - The entity, document, metric, or signal
2. **Source** - Where it lives (DB, API, user input, cache, logs)
3. **Availability**:
   - Always (can fetch 100% of the time)
   - Sometimes (depends on user actions or data freshness)
   - Never (must be requested explicitly or cannot be assumed)
4. **Sensitivity** - PII, internal-only, restricted, public

**Example output:**

```
| Data Needed          | Source      | Availability | Sensitivity |
|---------------------|-------------|--------------|-------------|
| User equity estimate | Internal DB | Always       | PII         |
| Browsing history    | Analytics   | Always       | Internal    |
| Stated goals        | User input  | Sometimes    | Internal    |
| Local market trends | API         | Always       | Public      |
```

**Flag problems immediately:**
- "Sometimes" availability needs a decision: What happens when it's missing?
- "Never" availability is a blocker: Can't build without resolving this

**Education moment:**
```
💡 Hidden dependencies live here. When you map honestly, you discover
   critical data that doesn't exist, sources that are unreliable, or
   assumptions that will break at scale.
```

### D3 — DISCOVERY: How Will You Get Context at Runtime?

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 D3: DISCOVERY — How will you get the context at runtime?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Knowing what data you need ≠ knowing how to get it at runtime.
   This is where "it worked in the demo" dies in production.
```

For each piece of context from D2:

1. **How will the system fetch this?**
   - Real-time query
   - Pre-computed/cached
   - User provides it
   - Inferred from behavior

2. **What's the latency budget?**

3. **What if the source is slow or unavailable?**

**Discovery strategies to consider:**

- **Search-Based:** Vector search (semantic), keyword search (precision), hybrid
- **Graph-Based:** Follow relationships through knowledge graph
- **Precomputed:** Daily/weekly jobs, materialized views, caches

**Education moment:**
```
💡 Trade-off: Real-time = fresh but slow. Cached = fast but stale.
   Know which context needs which strategy.
```

### D4 — DEFENSE: What Happens When It Fails?

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 D4: DEFENSE — What happens when it fails?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 AI will