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
Verification
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
1---2name: context-engineering3description: Build the smallest, highest-signal context package for an AI coding task — goal, constraints, repo facts, boundaries, and a verification plan. Load when prompts are underspecified, the agent is missing key files or decisions, the user says "use the right context", "here's the repo", or when work is drifting due to missing constraints. Also triggers on "context engineering", "gather context", "what do you need from me", "before you start". Not for cross-session continuity (use memory-startup/memory-recall).4license: MIT5---67# Context Engineering89You 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.1011## Hard Rules1213- Prefer **repo evidence** over guesses (read files, don’t assume).14- Context must be **purpose-driven**: every included item must support the goal, constraints, or verification.15- Separate **facts** from **assumptions**. Assumptions must be confirmable or safely reversible.16- Never mix cross-session memory with task context. Use `memory-startup`/`memory-recall` for that.17- If the task is blocked by missing context, ask **one** targeted question, not a questionnaire.1819---2021## Workflow2223### Step 1 — State the task in one sentence2425Write:2627```markdown28TASK: [one sentence]29```3031### Step 2 — Capture constraints and boundaries (5 bullets max)3233Include items like:34- Must not change: [APIs, files, behavior]35- Must preserve: [compat, performance, security, UX]36- Time/size constraints: [small PR, no new deps, etc.]37- Out of scope: [explicitly]3839### Step 3 — Choose a context tier4041Pick the smallest tier that makes progress safe:4243- **Tier A (micro)**: 1–3 files + reproduction steps (tiny fix)44- **Tier B (feature)**: spec/ACs + touched modules + tests (new feature / refactor)45- **Tier C (system)**: architecture + invariants + interfaces + rollout (cross-cutting change)4647### Step 4 — Collect the minimum evidence4849**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.5051Collect only what the tier requires:5253- **Graph facts** (if `docs/knowledge-graph/graph.json` exists): query 1-hop neighbors of touched modules via `query_graph.py`54- **Repo facts**: stack + relevant configs (package manager, build/test commands)55- **Locality**: entry file(s) for the change, plus direct callers56- **Contracts**: API surface, types/schemas, acceptance criteria57- **Verification**: how we’ll prove correctness (tests, manual steps, metrics)5859### Step 5 — Produce the context bundle (copy/pasteable)6061Use this template:6263```markdown64## Context bundle — [task slug]6566Goal:67- ...6869Constraints:70- ...7172Repo facts (evidence):73- [fact] (from [file])7475Key files:76- [path] — why relevant7778Interfaces/contracts:79- ...8081Assumptions (confirm or safe defaults):82- ...8384Verification plan:85- [ ] ...86```8788### Step 6 — Execute with context discipline8990While implementing, keep a short “context ledger”:91- If you discover a new constraint, add it and restate the plan.92- If you need another file, state why (what question it answers), then fetch it.9394---9596## Gotchas9798- “More context” often makes answers worse; irrelevant files dilute signal.99- If you don’t name constraints, you’ll violate them accidentally.100- Missing a verification plan leads to “looks good” shipping.101- Context for AI coding is **task-scoped**, not session-scoped — don’t conflate with memory.102103---104105## Common Rationalizations106107| Excuse | Reality |108|--------|---------|109| "Let’s just start coding and adjust later" | Unstated constraints cause large rewrites. Spend 2 minutes on a context bundle first. |110| "We should load the whole repo to be safe" | Noise increases mistakes; load only what answers the next question. |111| "I already understand the codebase" | The agent doesn’t — state the evidence and key files explicitly. |112| "Verification can wait until the end" | Without an upfront plan you’ll miss the easiest test hooks. |113| "This is just a small change" | Small changes still break contracts; Tier A context is cheap and prevents regressions. |114115---116117## Output Format118119```markdown120## Context engineering — [task]121122Tier: [A/B/C]123Context bundle: [included items]124Open questions: [0–2]125Next action: [exact next step]126```127128---129130## Examples131132<examples>133 <example>134 <input>“Fix failing tests in CI.”</input>135 <output>136Tier 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.137 </output>138 </example>139</examples>140141---142143## Verification144145- [ ] Task statement + constraints written before implementation starts146- [ ] Every included context item supports goal/constraints/verification147- [ ] Assumptions explicitly listed and confirmable or safely reversible148- [ ] Verification plan is stated upfront (tests/manual/metrics)149- [ ] Context stays minimal (no repo-wide dumps without a reason)150151---152153## Red Flags154155- Context gathered by guessing instead of repo evidence156- Irrelevant files included that dilute the task signal157- Constraints unnamed so violations go unnoticed158- Assumptions presented as facts without confirmation path159160## Prune Log161Last pruned: 2026-07-04162- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)163164165## Impact Report166167```168Task: [slug] | Tier: [A/B/C]169Key files: N | Assumptions: N | Verification items: N170Open questions: N171```
dvy1987