Assembling an Evidence-First Context Packet

Hello again. Last time, you audited persistent repository instructions: what is actually loaded, which rules are ambiguous or stale, and which requirements should be enforced by tooling rather than trusted to a model. That gives you a cleaner stable layer of context.

This lesson shifts to the task-specific layer: assembling an evidence-first context packet. For a .NET service change, Node.js defect, Elasticsearch relevance issue, or Kubernetes incident, the aim is to give the model the small set of artifacts that can justify a sound next action—not a repository dump and not a speculative summary.

By the end, you should be able to assemble a packet that separates facts from hypotheses, identifies its sources and time bounds, exposes contradictions, and gives Claude Code enough evidence to investigate or plan without inventing missing details.

---

Context is a working set, not an archive

Prompt engineering concerns how you phrase an ask. Context engineering concerns everything the model sees while answering: repository instructions, the ticket, code, tests, retrieved documentation, logs, tool descriptions, and recent conversation.

For an engineering task, the key question is not “What might be useful?” It is:

What information could materially change the proposed implementation, diagnosis, validation, or safety decision?

A model given every related file, every historical discussion, and several days of logs has more tokens, but not necessarily more usable evidence. Large, mixed context tends to create four predictable failures:

• Contamination: an unsupported claim becomes treated as fact in later reasoning.
• Distraction: a long history receives attention even though it is no longer relevant.
• Confusion: incidental details pull the model toward an irrelevant explanation.
• Clash: two sources disagree, but the model silently selects one.

Watch this concise overview from Google Cloud Tech before applying the method.

An evidence-first packet treats context as a versioned case file for one decision. It should let another engineer answer:

1. What task is being requested?
2. What is directly observed, and where did it come from?
3. What constraints must remain true?
4. What is uncertain or contradictory?
5. What response is wanted from the model at this stage?

The packet is not necessarily a single file. It can be a carefully structured prompt, a GitHub issue with linked artifacts, or a session in which Claude is explicitly asked to inspect named files and commands before it reaches conclusions.

---

Begin with the decision, then derive the evidence questions

Do not collect artifacts by technology category alone. Start with the decision you need help making.

For example:

Task	Decision the model should support	Evidence questions
.NET API defect	What likely causes the behavior, and what change is safe to make?	Which request path executes? What contract is expected? What regression test demonstrates it?
Node.js feature	What is the smallest implementation that meets the acceptance criteria?	Which package owns the behavior? Which existing pattern is authoritative? Which type and test commands apply?
Elasticsearch regression	Is the ranking or latency regression caused by query construction, mapping, data, or load?	What query was issued? Which mapping and deployment revision were active? What changed around the onset?
Kubernetes incident	What should be investigated or mitigated first?	What is the impact and time window? Which workload revision is running? What do metrics, logs, and traces show?

This ordering prevents a familiar failure mode: placing an entire src/ tree into context before determining whether the model needs a controller, a query builder, a test fixture, or an Elasticsearch mapping.

A useful collection sequence is:

1. Frame the decision. State the requested outcome, affected system, environment, and non-negotiable constraints.
2. List evidence questions. Turn vague research into answerable questions such as “Which revision introduced the behavior?” or “Where is tenant filtering applied?”
3. Gather the smallest authoritative artifacts. Prefer direct evidence over summaries.
4. Record what each artifact establishes. A file path alone is not a claim.
5. Mark gaps and conflicts. Do not silently fill them with plausible assumptions.
6. Ask for a bounded response. For instance, request an investigation plan, not an immediate production fix.

The first goal is not to prove a root cause. It is to ensure that the model can distinguish observations, inferences, and unknowns.

---

What to collect from each evidence source

Code: capture the behavioral path, not a directory snapshot

Code evidence should enable the model to trace the relevant behavior end to end. For a typical .NET endpoint backed by Elasticsearch, that usually means:

• the endpoint, controller, or message consumer that receives the request;
• the application service or handler that coordinates the behavior;
• the query builder, repository, or client adapter that constructs the Elasticsearch call;
• the relevant request and response contracts;
• configuration that changes behavior, such as index aliases, timeouts, feature flags, or endpoint selection;
• a caller or downstream component when its contract constrains the change.

For Node.js, the equivalent may be a route handler, service module, validation schema, database or search adapter, package script, and closest consumer.

Avoid adding generated output, package lockfiles, entire solution files, or unrelated shared utilities merely because they are nearby. Include them only when they establish a dependency, version constraint, or reproducible command that matters to the task.

Every code item should be identified by a stable reference where possible:

Field	Example
Source	src/Search.Api/Features/Catalog/SearchHandler.cs
Revision	Current branch and commit SHA, or a named pull request diff
Relevant range	The handler and the method that builds the query
Establishes	Tenant filter is applied before the Elasticsearch request
Limits	Does not show production query latency or index mappings

That final field matters. A handler can explain what the service intends to send. It cannot prove what a particular production pod sent at a particular time.

Tests: evidence of expected behavior, not the entire specification

Tests are particularly valuable because they turn an informal expectation into an executable example. Include:

• the closest unit, integration, or contract test;
• fixtures that represent the reported input;
• current failures, including the command used and relevant output;
• the repository’s documented targeted validation command;
• tests near a likely boundary, such as authorization filtering or serialization.

Tests should not be treated as complete truth by default. A missing test may expose a gap; a poorly scoped test may codify an old behavior; and a green test suite does not demonstrate that an operational regression cannot occur. Still, a focused test is often the best anchor for a model’s proposed regression coverage.

Tickets: preserve the report, extract its claims

A ticket commonly contains the request, user impact, reproduction steps, and a mixture of useful clues and speculation. Preserve the distinction.

Google’s SRE guidance identifies the core of a useful problem report: expected behavior, actual behavior, and reproduction information. Read the “Problem Report” subsection for a compact model of what to preserve from an issue.

For a ticket, extract these fields into the packet:

• Reported impact: who or what is affected.
• Expected behavior: a measurable or observable result.
• Actual behavior: including error text, status code, ranking result, or latency.
• Reproduction: input, sequence, account or tenant conditions if relevant, and environment.
• Acceptance criteria: what “done” means.
• Reporter hypotheses: retain them, but label them as hypotheses rather than facts.
• Open ambiguities: missing version, missing time window, conflicting reports, or unclear ownership.

A GitHub issue can also be the durable home for the packet and its evolving investigation record, especially when work crosses context windows.

The workflow below from Matt Pocock demonstrates storing a phased plan in a GitHub issue, clearing the active context, and retrieving the relevant phase later. The same pattern works for an evidence manifest, provided the issue links to the actual code, logs, dashboards, and validation results rather than replacing them with an unsupported narrative.

Documentation: include the source of a constraint

Documentation earns a place in the packet when it establishes a contract that code alone cannot make clear. Typical examples include:

• an ADR that defines a compatibility or data-ownership boundary;
• an API contract or public behavior specification;
• an Elasticsearch index and mapping migration procedure;
• an incident runbook with a defined mitigation boundary;
• a deployment or rollback procedure;
• an architecture diagram that explains a cross-service dependency.

Prefer current, owned documents over copied notes. Identify the relevant section and explain what it establishes. A broad “architecture overview” is usually too vague; an ADR excerpt saying that authorization filters must be applied before search queries is a concrete constraint.

Operational data: bind every observation to time, environment, and revision

Operational evidence often turns a plausible code-level theory into a testable hypothesis. It is also the easiest evidence to misuse because logs and dashboards are noisy.

For any production or staging observation, capture:

• environment and cluster or namespace;
• service name, pod or deployment revision, and image version;
• a bounded time window, ideally in UTC;
• baseline comparison period;
• relevant metric definition, such as p95 latency or error rate;
• correlated request, trace, or transaction IDs where available;
• selected log entries that correspond to the time window and component;
• recent deployment, configuration, index, or feature-flag changes.

The SRE Book’s “Examine” and “What touched it last” discussions explain why metrics, logs, tracing, current state, and recent configuration or deployment changes should be considered together.

Do not paste a day of raw Kubernetes logs or unrestricted Elasticsearch responses into a packet. Select a small set of representative, redacted excerpts tied to the observed failure. Keep raw data available through approved tools or links, where the model can retrieve more if its next investigation step justifies it.

---

Use an evidence manifest to make provenance visible

The most useful packet structure is a short task frame followed by an evidence manifest. The manifest prevents the model and reviewer from treating every supplied artifact as equally authoritative.

Here is a compact template:

ID	Type and source	Scope and time	Establishes	Confidence or limitation
E1	Ticket or issue	Reporter, environment, date	Reported expected and actual behavior	Reported observation; not independently verified
E2	Code excerpt at revision	Named files and ranges	Current request path and constraints	Does not prove runtime behavior
E3	Test and result	Test name and command	Existing executable expectation	May omit production conditions
E4	ADR, contract, or runbook	Specific section	Required design or operational constraint	Confirm currency and owner
E5	Metric, trace, log, or event	Environment and UTC window	Runtime observation or change event	Correlation is not causation

Add two explicit sections after the manifest:

• Known unknowns: missing information that blocks a confident conclusion.
• Contradictions: sources that disagree and must be reconciled.

For example:

Known unknown:
No trace links the slow requests to a specific Elasticsearch query.

Contradiction:
The ticket says the regression began after release 2025.06.
Deployment history shows no application rollout during the reported window,
but an index alias change occurred shortly before it.

This is better than asking the model to “investigate a performance regression” and allowing it to fabricate a causal narrative. A good model response can now say: “The evidence supports investigating the alias change first; it does not yet establish causation.”

---

Assemble a packet for a search regression

Assume this illustrative ticket:

Catalog search p95 latency rose from 350 ms to 2.4 s in production. It affects filtered searches for large tenants. The issue began during the morning release window. Results must remain tenant-isolated.

A weak prompt would attach the ticket and say, “Find the bug.”

An evidence-first packet asks for a narrower decision: produce an investigation plan and identify the minimum additional evidence needed before proposing a fix.

ID	Selected evidence	Why it belongs
E1	The issue’s expected latency, actual latency, affected request shape, and tenant-isolation requirement	Defines impact and the critical safety invariant
E2	The API endpoint, search handler, and Elasticsearch query-builder method	Shows how filters and query clauses are constructed
E3	The closest integration test for filtered catalog search and its fixture	Shows the current executable expectation
E4	The current mapping or index-alias configuration and its revision history	Determines whether query behavior could have changed without a code deploy
E5	Production p50, p95, p99 latency and error rate for a bounded window, compared with a baseline	Establishes the shape and onset of the regression
E6	A small set of correlated traces or slow-query logs, redacted and tied to the same window	Connects request behavior to downstream work
E7	The search runbook section defining safe diagnostic actions and prohibited production writes	Prevents an investigation plan from proposing unsafe cluster changes

Notice the exclusions:

• unrelated catalog endpoints;
• all historical search incidents;
• raw logs from other namespaces;
• an entire Elasticsearch index export;
• generated client files that do not affect query construction;
• a reporter’s “it must be Elasticsearch” assertion.

Those items may become relevant later, but they do not belong in the initial working set without evidence that they change the next decision.

The packet should also preserve a distinction that is crucial in AI-assisted work:

Category	Example
Fact	A trace shows the request spent 1.8 seconds in a specific search call.
Constraint	Tenant filtering must remain server-enforced.
Hypothesis	The mapping change increased query cost for a filter clause.
Unknown	Whether the slow trace used the new index alias.
Requested work	Produce a ranked investigation plan; do not modify deployment or index settings.

A hypothesis is valuable when labeled. It tells the model where to inspect next without granting it the status of evidence.

---

Package the information so the model can use it

Once you have selected the artifacts, structure them clearly. For large inputs, Anthropic recommends placing long-form documents before the query and asking the model to ground work in quoted evidence. It also recommends investigating code before making codebase claims.

Within the user-level task content, use explicit labels or XML-like boundaries. This does not make a ticket or log trustworthy; it makes the role of each item unambiguous.

<task>
Create an investigation plan for the catalog-search latency regression.
Do not change code, Elasticsearch settings, or Kubernetes resources.
Preserve tenant isolation. Cite evidence IDs for each recommendation.
</task>

<evidence_manifest>
E1: GitHub issue 184, production report, current as of [timestamp].
E2: Search endpoint and query-builder excerpts at [commit SHA].
E3: Filtered-search integration test and latest result.
E4: Index alias and mapping change record.
E5: Production latency metrics for [UTC window] and baseline.
E6: Three correlated traces and redacted slow-query excerpts.
E7: Search incident runbook, safe read-only diagnostics section.
</evidence_manifest>

<known_unknowns>
No trace currently proves which index alias served the slow requests.
</known_unknowns>

<requested_response>
First list evidence-backed observations and contradictions.
Then propose up to five read-only investigation steps, ordered by expected
information gain. For each step, state which uncertainty it resolves.
</requested_response>

For a direct long-context prompt, put the substantial evidence blocks above this concise task frame, as the documentation recommends. Keep trusted repository instructions in their normal system or project-memory layer; do not blur them together with a ticket, log excerpt, or retrieved document.

A particularly strong response requirement is:

Before recommending an action, list the evidence IDs and quoted observations that support it. Label any remaining conclusion as an inference.

That request makes the model show its work. It will not eliminate errors, but it makes unsupported leaps visible during review.

---

A final quality gate before sending the packet

Before asking Claude Code to plan, diagnose, or implement, scan the packet against this gate:

• Decision: Is the requested outcome specific and bounded?
• Provenance: Does each important artifact have a source, revision or timestamp, and scope?
• Authority: Is it clear which source defines requirements when ticket, test, and documentation differ?
• Relevance: Can you explain why every included artifact could change the next action?
• Freshness: Are deployment state, configuration, metrics, and code references current enough for the task?
• Separation: Are facts, constraints, hypotheses, and unknowns visibly distinct?
• Operational precision: Are environment, UTC time window, deployment revision, and baseline present when using runtime data?
• Safety: Have secrets, tokens, personal data, and unnecessary customer payloads been excluded or redacted?
• Evidence discipline: Does the requested response require citations, uncertainty reporting, and no invented validation?
• Action boundary: Does the task state whether the model may only investigate, may edit code, or needs approval before any consequential action?

If the packet fails this gate, the right next step is usually not “ask the model anyway.” It is to obtain the missing artifact, narrow the task, or ask the model for targeted clarification questions.

---

An evidence-first context packet is a compact, inspectable case file: a task frame, a manifest of selected sources, explicit constraints, time-bounded operational observations, and visible unknowns. Code explains intended behavior; tests provide executable expectations; tickets define reported impact; documentation establishes contracts; operational data shows what actually happened. None is sufficient alone in every case.

Next, you will use such a packet to review an AI-generated implementation plan against architecture, testing, observability, and rollback constraints—turning grounded investigation into a change plan that is safe to execute.