Context Engineering

You construct a minimal, task-relevant context bundle that prevents rework. You do not "load everything"; you load the smallest set of facts that make the next step safe.

Hard Rules

• Prefer repo evidence over guesses (read files, don’t assume).
• Context must be purpose-driven: every included item must support the goal, constraints, or verification.
• Separate facts from assumptions. Assumptions must be confirmable or safely reversible.
• Never mix cross-session memory with task context. Use memory-startup/memory-recall for that.
• If the task is blocked by missing context, ask one targeted question, not a questionnaire.

---

Workflow

Step 1 — State the task in one sentence

Write:

TASK: [one sentence]

Step 2 — Capture constraints and boundaries (5 bullets max)

Include items like:

• Must not change: [APIs, files, behavior]
• Must preserve: [compat, performance, security, UX]
• Time/size constraints: [small PR, no new deps, etc.]
• Out of scope: [explicitly]

Step 3 — Choose a context tier

Pick the smallest tier that makes progress safe:

• Tier A (micro): 1–3 files + reproduction steps (tiny fix)
• Tier B (feature): spec/ACs + touched modules + tests (new feature / refactor)
• Tier C (system): architecture + invariants + interfaces + rollout (cross-cutting change)

Step 4 — Collect the minimum evidence

Corpus gate (Tier B/C): If the repo has >500 scannable files or the task touches >20 paths, narrow scope to the smallest subdirectory that contains the change before loading files.

Collect only what the tier requires:

• Graph facts (if docs/knowledge-graph/graph.json exists): query 1-hop neighbors of touched modules via query_graph.py
• Repo facts: stack + relevant configs (package manager, build/test commands)
• Locality: entry file(s) for the change, plus direct callers
• Contracts: API surface, types/schemas, acceptance criteria
• Verification: how we’ll prove correctness (tests, manual steps, metrics)

Step 5 — Produce the context bundle (copy/pasteable)

Use this template:

## Context bundle — [task slug]

Goal:
- ...

Constraints:
- ...

Repo facts (evidence):
- [fact] (from [file])

Key files:
- [path] — why relevant

Interfaces/contracts:
- ...

Assumptions (confirm or safe defaults):
- ...

Verification plan:
- [ ] ...

Step 6 — Execute with context discipline

While implementing, keep a short “context ledger”:

• If you discover a new constraint, add it and restate the plan.
• If you need another file, state why (what question it answers), then fetch it.

---

Gotchas

• “More context” often makes answers worse; irrelevant files dilute signal.
• If you don’t name constraints, you’ll violate them accidentally.
• Missing a verification plan leads to “looks good” shipping.
• Context for AI coding is task-scoped, not session-scoped — don’t conflate with memory.

---

Common Rationalizations

Excuse	Reality
"Let’s just start coding and adjust later"	Unstated constraints cause large rewrites. Spend 2 minutes on a context bundle first.
"We should load the whole repo to be safe"	Noise increases mistakes; load only what answers the next question.
"I already understand the codebase"	The agent doesn’t — state the evidence and key files explicitly.
"Verification can wait until the end"	Without an upfront plan you’ll miss the easiest test hooks.
"This is just a small change"	Small changes still break contracts; Tier A context is cheap and prevents regressions.

---

Output Format

## Context engineering — [task]

Tier: [A/B/C]
Context bundle: [included items]
Open questions: [0–2]
Next action: [exact next step]

---

Examples

<examples> <example> <input>“Fix failing tests in CI.”</input> <output> Tier A. Collect: failing command, CI logs, the test file, and the code under test. Add constraints: no snapshot regen unless approved. Verification: `npm test` locally and CI rerun. </output> </example> </examples>

---

Verification

• Task statement + constraints written before implementation starts
• Every included context item supports goal/constraints/verification
• Assumptions explicitly listed and confirmable or safely reversible
• Verification plan is stated upfront (tests/manual/metrics)
• Context stays minimal (no repo-wide dumps without a reason)

---

Red Flags

• Context gathered by guessing instead of repo evidence
• Irrelevant files included that dilute the task signal
• Constraints unnamed so violations go unnoticed
• Assumptions presented as facts without confirmation path

Prune Log

Last pruned: 2026-07-04

• No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Task: [slug] | Tier: [A/B/C]
Key files: N | Assumptions: N | Verification items: N
Open questions: N