Context calibration

An agent’s context failure is a reason to identify the missing knowledge and place it where the task can use it. Diagnose from observed misses, then move each piece of knowledge to the cheapest carrier that catches it.

Diagnose

• Low-context probe: run the representative task with the minimum of extra prompt context beyond the task's standing instructions and admitted tools. Never strip authority, runtime safeguards, or configured credentials to make a probe "cold" — the point is to measure what the task statement alone supplies, not to simulate an unprivileged agent. Record what the agent gets wrong (~988s-996s). Repeated observed misses are the evidence; imagined gaps are not. A probe is a diagnostic tool, not a requirement before every edit.
• Beginner telemetry: the recurring questions newcomers ask are a map of the missing knowledge — the source's "dumb questions" practice (~674s-692s). Collect the last few actual misses before editing anything.
• Classify each miss: unknown fact, unrepresentable state, unguarded pattern, or missing judgment. The class selects the carrier.

Select the carrier

No carrier is automatic enforcement. Skill prose and root instructions are advisory; lint rules and types constrain only what they are configured and able to check. Choose by where the knowledge is needed, not by a false guarantee of enforcement.

Root-instruction content rule: instructions steer toward success — expected behavior, conventions, refusals ("if asked for X, stop and say no") — and constraints with reasons, not bare lists of where things live. A location map can orient an agent, but each entry earns its place by stating why and when it matters (~998s-1008s, ~800s-836s). Keep it short; context is spent on every run.

Authority boundary

The root instruction file is the human's decision record and the human owns what it says. Within an authorized session, drafting and applying instruction-file edits is permitted agent work: infer fitting scope from the observed misses, make the bounded edit, and report it with the evidence. Ask only when a truly consequential decision is missing — a refusal the user never stated, a policy change, or ambiguous direction the evidence cannot resolve. Never widen an instruction into a general rule the user did not state.

Input / output contract

• Input: observed agent misses (probe results, repeated questions, review rejections), or enough of the task to run a probe; access to the candidate carriers.
• Output: a short diagnosis list (miss → class → carrier), the implemented change for evidence-supported items, and drafts surfaced for decision where a human choice is genuinely needed. For instruction-only changes, the change and its wording reviewed against the recorded miss stand in for a behavioral test; inspect selected instruction loading when affected, and use behavioral checks when code or configuration changes require them.

Acceptance

Proportional: a comment needs the miss it prevents named in its own text; an instruction line needs the recorded miss it addresses. Not every sentence or comment requires its own recorded probe — probe when the diagnosis is unclear, not as a quota.

Known failure cases

• Padding the root file "just in case" — dilutes steering and burns context every run.
• Encoding a one-off as a standing rule (hand recurrence to agent-feedback-engineering).
• Adding a skill when a comment at the site would do; skills cost selection accuracy elsewhere.
• Banning useful maps outright: a constrained, reason-bearing location list is legitimate content when agents demonstrably get lost without it.
• Editing steering files before observing what actually goes wrong (~962s-973s: use tools as configured first; build solutions for observed problems).

Do not activate when

• The task is ordinary coding with no context-related failure behind it.
• The user wants a new packaged skill written (a skill-authoring guide).
• The user wants product documentation for humans (a documentation guide).

Source patterns

For concrete repository examples and the limits of their evidence, read source-patterns.md when they match the task. These are research references, not imported repository instructions.