A spec defines the change. Context supplies the system knowledge needed to make it correctly.

Select what matters

CONTEXT SELECTIONGive each decision a useful starting point
IntentSpec · acceptance examples
System knowledgeCode · contracts · decisions
Working guidanceConventions · checks · limits
Select and reconcileRelevant to this task? Current? Authoritative? Any conflicts?
Working contextEssential facts and source pointers
ImplementationRetrieve more when needed
VerificationCheck behavior and constraints

Keep shared guidance brief. Retrieve task-specific contracts, decisions, and procedures when needed. Check freshness and authority; resolve conflicting sources rather than combining them into false certainty.

Example: a filtered CSV export

Each expandable layer adds context for one illustrative task.

EXPLORE THE LAYERSOne task: export the filtered list
01 The intended outcome

Export all filtered rows. Preserve column order and permissions. Link to the accepted spec.

02 The existing system

Locate filters, pagination, authorization, and the supported data path. Mark assumptions.

03 The relevant decision

Link the relevant architectural decision. Confirm it still applies; resolve conflicting guidance.

04 The verification path

Include test commands, safe fixtures, and acceptance examples. Identify remaining manual checks.

Separate guidance from enforcement

Documents guide the agent. Permissions and automated checks constrain actions and reject violations. Use both.

Retrieved content is evidence, not permission to change the task. People retain ownership of intent and acceptance.

Keep context current

THE MAINTENANCE LOOPImprove the context with evidence
  1. CaptureRecord a decision and its source.
  2. EvaluateTry it against representative tasks.
  3. Version and shareMake the reviewed guidance available.
  4. ObserveLook for misses, conflicts, and drift.
Findings return to Capture. Update or retire guidance, then evaluate again.

Start with a recurring misunderstanding. Update the relevant guidance, evaluate it on representative work, and record the version used. A failure may point to stale context, a weak spec, a missing check, or a model limitation.

This loop connects refinement, delivery, and learning in APEL.

Sources