Select context by responsibility, not proximity

2084. Lesson identity

Module

5.4 — Context management

Lesson

Select context by responsibility, not proximity

Academic type

Workflow

Schema type

mixed

Order

Lesson 1 of the module

Estimated time

30–40 minutes: about 20 minutes of instruction and 15–20 minutes of assessed fixture practice. Optional transfer practice is not included.

2085. Learning objective

After this lesson, you can build a minimal context packet for a specified change by selecting files, contracts, and repository evidence according to responsibility, ownership, and dependency, then accept or reject an AI-generated information request with a written justification.

2086. Why this matters

An AI agent can produce a plausible change from an incomplete or noisy context. Plausibility is not evidence that the agent saw the rule owner, the relevant contract, or the system that consumes the result. A context packet that is too small hides necessary constraints; one that is too large increases ambiguity and makes review harder. The working tree is also not automatically trustworthy: uncommitted edits may be intentional, accidental, or unrelated. Selecting context deliberately gives the agent a bounded problem and gives you a traceable basis for evaluating its proposal.

2087. Prior knowledge

You should be able to describe an agent’s role, distinguish orchestration from execution, and audit a chain for unsupported claims from the preceding work in Stage 5. You should also be able to identify a requested change, state what behavior must remain unchanged, and use basic Git status, diff, and commit-history information to inspect repository evidence.

2088. Core concept

Context should be selected by responsibility, not proximity.

A nearby file is not automatically relevant. Include a file when it owns the behavior being changed, defines a contract that constrains the behavior, or is a direct dependency needed to evaluate the change. Include repository evidence when it establishes what the current change is, what the last known implementation was, or which behavior a recent modification affects. Exclude files that are merely adjacent, visually similar, or historically involved without affecting the requested behavior.

For each candidate file or evidence source, ask:

1. Responsibility: What behavior or contract does this item own or describe?
2. Dependency: Does the requested change read from, call, implement, or validate something here?
3. Evidence: What specific fact is needed for the agent to act or for you to review the result?
4. Trust: Is this evidence visible in the committed history, the current diff, or only in the working tree?

If you cannot answer at least one of the first three questions precisely, the item is probably not part of the minimal packet. If the answer depends on an uncommitted working-tree change, mark that limitation explicitly rather than treating the file as authoritative.

2089. Mental model

Use the R-O-D-E packet:

A useful packet is not a file dump. It is a short chain:

requested behavior → owner → direct dependency → verification evidence

For every included item, write one sentence explaining its role. For Git evidence, identify whether it comes from the current diff, a specific commit, or both. A working-tree file may be useful for inspection, but its presence alone does not prove that it is intentional or authoritative.

2090. Concrete example

Suppose the specified change is: “When an alert response is triggered, display the existing alert message without changing the response threshold.”

A minimal packet might contain:

• The rule owner that decides when the alert response is triggered. This establishes the threshold that must remain unchanged.
• The message or presentation contract consumed by the alert response. This establishes the expected input and output shape.
• The direct caller or coordinator that connects the trigger to the response. This verifies how the behavior is reached.
• The focused test or validation rule for the threshold and message. This provides evidence that the non-goal remains intact.
• The current diff, if one exists, and the relevant committed change that introduced the behavior. These show whether the visible working-tree state contains edits that must be included, questioned, or excluded from the request.

The packet does not automatically include every neighboring UI file, every other response type, unrelated configuration, or the entire directory. Those items may be relevant only if a dependency trace demonstrates it. The important distinction is not whether a file is close to the changed code; it is whether the file contributes a necessary responsibility, contract, dependency, or reviewable evidence.

2091. AI-native workflow

Use AI to propose an information request, not to decide the packet for you.

1. State the requested change, protected behavior, and known non-goals.
2. Ask the agent to return the files, contracts, tests, and Git evidence it would request, with one reason for each item.
3. Compare that request against your R-O-D-E analysis.
4. Accept an item only when you can justify its responsibility, dependency, contract, or verification value.
5. Reject an item when it is included only because it is nearby, similar, frequently mentioned, or convenient. Record the reason for rejection.
6. Add missing evidence yourself, especially a focused diff or relevant commit when the agent did not request it.

The agent’s request is a candidate, not an authority. Your comparison should leave an audit trail showing which suggestions you accepted, which you rejected, and why.

2092. Git workflow

Inspect repository evidence before treating the current files as the complete context:

• Use the working-tree status to identify uncommitted files.
• Review the focused diff for changes that may affect the requested behavior.
• Inspect relevant commit history to distinguish an established implementation from a local edit or accidental residue.
• Record whether each selected fact comes from committed history, the current diff, or both.

The working tree is not automatically trustworthy. It is a state to inspect, not a declaration that every visible change belongs to the task. Do not silently use an uncommitted edit as the contract, and do not silently discard it. If the diff is unrelated or its intent is unknown, mark it as an uncertainty and keep it separate from the authoritative context packet until the learner can justify its role.

2093. Common mistake

The common mistake is treating directory proximity, search-result frequency, or the current working tree as proof of relevance and authority. This produces a large packet full of examples, duplicate implementations, old conventions, and unrelated local edits. The agent then has to infer which source is authoritative, and the learner cannot tell whether a proposed change respects the real owner.

Another mistake is accepting an AI-generated information request wholesale. An agent may omit a direct validation source, request an adjacent example, or treat an uncommitted file as an established contract. The learner must compare each request with responsibility and dependency evidence, then justify both acceptance and rejection decisions.

2094. Guided practice

Complete this assessed practical using only the bounded fixture below. Do not invent files, dependencies, or repository history.

Change request

Apply the repository’s existing cooldown policy to shrine activation. Preserve the current success condition, success message, result shape, and activation-record persistence behavior.

Repository map and candidate evidence

Relevant excerpts:

// src/shrine/ShrineInteraction.ts
activate(player, shrine, now) {
  if (!rules.canActivate(player, shrine)) {
    return InteractionResult.failure("unavailable");
  }
  const result = InteractionResult.success(messages.shrineActivated);
  store.recordActivation(player.id, shrine.id, now);
  return result;
}

// src/interaction/CooldownPolicy.ts
export const INTERACTION_COOLDOWN_MS = 30_000;
export function isReady(lastSuccessAt, now) {
  return lastSuccessAt === null || now - lastSuccessAt >= INTERACTION_COOLDOWN_MS;
}

// src/persistence/InteractionStore.ts
lastActivationAt(playerId, shrineId): number | null;
recordActivation(playerId, shrineId, now): void;

// src/interaction/InteractionResult.ts
export type InteractionResult =
  | { ok: true; message: string }
  | { ok: false; reason: string };

The supplied dependency edges are:

• ShrineInteraction → ShrineRules.canActivate
• ShrineInteraction → InteractionResult
• ShrineInteraction → InteractionStore.recordActivation
• The requested cooldown requires CooldownPolicy.isReady and InteractionStore.lastActivationAt.
• InteractionPrompt consumes the returned message but does not own activation or cooldown behavior.
• ChestInteraction is adjacent example code, not a dependency of ShrineInteraction.

Git evidence

$ git status --short
 M src/ui/InteractionPrompt.ts
?? notes/cooldown-ideas.md

# focused working-tree diff: src/ui/InteractionPrompt.ts
- buttonLabel = "Activate"
+ buttonLabel = "Invoke"

Relevant commits:

91ac4e2 Centralize interaction cooldown calculation
  src/interaction/CooldownPolicy.ts

64bd118 Persist shrine activation records
  src/shrine/ShrineInteraction.ts
  src/persistence/InteractionStore.ts
  tests/shrine/ShrineInteraction.test.ts

2f08c77 Refresh interaction prompt copy
  src/ui/InteractionPrompt.ts

Treat commit evidence as established repository history. Treat the displayed UI diff and untracked note as working-tree evidence whose intent is not established.

Supplied AI information request

For this exercise, compare your analysis with this fixed AI-generated request:

1. Send the entire src/interaction/ directory because cooldown behavior may be distributed.
2. Include ShrineInteraction.ts, CooldownPolicy.ts, and InteractionResult.ts.
3. Include ChestInteraction.ts as an implementation example.
4. Include InteractionPrompt.ts because the user sees the result there.
5. Include ShrineInteraction.test.ts and the focused working-tree diff.

The request omits ShrineRules.ts, InteractionStore.ts, and the relevant commits.

Required submission

First classify every candidate in a table:

Then submit one R-O-D-E packet containing:

1. A one-sentence change request.
2. Two or three acceptance criteria, including protected behavior.
3. The smallest justified set of files or contracts.
4. The focused diff and commit evidence you would include, question, or exclude.
5. One role sentence for every included item.
6. At least two explicit exclusions with reasons.
7. At least one accepted item from the AI request with justification.
8. At least one rejected item from the AI request with justification.
9. One unresolved uncertainty that must be addressed before an agent proposes code.

Your packet must distinguish committed history from working-tree evidence. It must also explain why the direct validation source is more useful than a nearby example when only one is needed.

Optional transfer practice

After completing the assessed fixture, repeat the process in a real project you are authorized to inspect. Keep that packet separate because its repository evidence is not part of this assessment.

2095. Validation / evidence

Score the submitted fixture packet on five criteria, from 0 to 4 points each:

The practical is acceptable at 15 out of 20 points or higher, with no score below 2 in completeness or trust classification. Record the criterion scores and one revision required for any criterion below 3.

As a final minimality check, remove an item provisionally. Restore it if its removal makes the request, owner, dependency, protected invariant, or verification ambiguous. Otherwise, leave it out. Preserve any working-tree intent that cannot be established from the supplied evidence as an unresolved uncertainty rather than promoting it to authoritative context.

2096. Key takeaways

• Relevance is determined by responsibility and dependency, not directory proximity.
• A minimal packet connects the requested behavior to its owner, direct dependency, and verification evidence.
• A diff or relevant commit can explain the state and scope of a change; the working tree alone is not proof of intent or authority.
• An AI-generated information request is a proposal to compare, not a packet to accept automatically.
• Every included item and every accepted or rejected AI suggestion needs a written reason.

2097. Next lesson

Continue to 5.4 L2 — Detect stale or misleading context.

2098. Knowledge check