Pattern Matrix/White Paper/P1

P1 · Context Triage

What problem it solves

The normal state of a production-grade Agent is not too little information but too much. A medium codebase plus three weeks of git history runs to 180K tokens before anything else, and an enterprise knowledge base far exceeds any window. When the candidate information will not fit, the most naive truncation (sort by filename and cut the back half) leaves behind stale material and drops critical evidence, so the Agent reaches a wrong conclusion while believing it has seen a complete set.

Context triage turns this into an engineering process: it divides all candidate information into four levels, P0/P1/P2/P3, and loads from high to low until the token budget runs out. It governs window allocation for a single request, with the goal of guaranteeing that the most critical information is not drowned out.

Why the coordinate is "Perception × Route"

• Vertical axis · Perception: Triage decides what the Agent looks at and what it ignores; it is attention management on the perception side. It handles the stage before information enters reasoning, not the adjustment of output format and not cross-session memory.
• Horizontal axis · Route: Information of different priorities takes different processing paths—high priority enters context, medium priority is compressed into a summary, low priority is only attached as a handle to be pulled on demand. This is a single routing decision based on the characteristics of the information, not a chained sequence and not a looped iteration.

Core mechanism

A single triage layers the candidate information by priority, then uses the token budget to allocate a quota to each layer:

Three engineering points decide whether triage succeeds or fails. First, the priority judgment comes from one of two routes: manual triage (such as Claude Code's five-level CLAUDE.md hierarchy, where the developer themselves puts safety rules at P0 and personal preferences at P2) and algorithmic triage (such as Aider's RepoMap, which uses tree-sitter to extract symbols and scores them with a graph algorithm). Second, the error stack is specially protected and is never triaged away—it is the Agent's feedback loop, and losing it makes the Agent repeat the same mistake. Third, every triage decision must produce a trace; otherwise it is impossible to tell in production whether a critical file was dropped by triage or never discovered at all.

Production scenarios where it fits

• Multi-tenant SaaS customer-service Agent: One Agent serves hundreds of tenants, each with a knowledge base on the order of 300,000 tokens, far exceeding the window in total. tenant_id must be made a hard P0 constraint, with the rest of the knowledge triaged across the four levels.
• Code Agent facing an unfamiliar codebase: The user supplies a different repository each time, and you cannot require everyone to write a CLAUDE.md, so you must take the route of automatic algorithmic symbol extraction.
• Engineering Agent serving the same team long term: Investing in a hand-written 200-line CLAUDE.md to buy triage accuracy is more efficient than the algorithmic route.
• Any Agent connected to a file system, a knowledge base, or running more than five rounds: Once the information can possibly exceed the window, triage becomes unavoidable.

Where it tends to go wrong

• Priority misjudgment: Marking a file as P3 when it is the key to the bug means the Agent has to run an extra retrieval loop midway to pull it back, burning another 5K-10K tokens and raising the risk of cascading errors. When in doubt, upgrade; carrying one extra small file is cheaper than running one extra loop.
• Over-aggressive triage: Capping the budget too tightly to save tokens suspends the whole critical dependency chain, and the Agent repeatedly says "I need to read this file again." The re-read ratio climbs, and the tokens saved are spent again on re-reading.
• Vague P3 handle naming: A name like doc://manual-page-3 leaves the Agent unsure whether to fetch it. Handle names should carry a "what is this" signal and follow a three-part "hierarchy + topic + time" form.
• Cross-tenant data leakage: A P3 handle fetching the wrong tenant's data into the context is a data-breach incident. A resource with a tenant prefix must be force-validated against the P0 tenant_id at load time.
• Trace sampled away: A 1% sampling rate for storage control cannot reveal that "a certain tenant has been leaking data across tenants the whole time." Triage traces go to full structured logging, with storage controlled by counting rather than sampling.

Key metrics

• re-read ratio (healthy zone < 5%): The fraction of times the Agent requests, mid-reasoning, to re-read a suspended file. Above 10% is a clear signal of over-aggressive triage, and every re-read is a full reasoning loop.
• p99 of dropped_count (watch the long tail, not the mean): The mean hides the problem; the p99 exposes the long-tail failure where "1% of requests trigger a triage avalanche and the Agent sees almost nothing."
• p3_hit_rate (healthy zone 10-30%): The fraction of P3 handles that are actually fetched. Below 5% means the handles are attached too broadly and waste tokens; above 50% means things that should be P2 were wrongly downgraded to P3.

Minimal implementation skeleton

对候选信息按优先级排序（P0 > P1 > P2 > P3，错误堆栈额外加分）：
                逐条塞入：
                    P3            → 进句柄池，不预加载
                    其余 + 未超预算 → 进 context，累加 token
                    其余 + 超预算   → 丢弃（但错误堆栈强制保留）
            返回 (进 context 的, 挂句柄的, 一条 TriageDecision)
            TriageDecision 留下：时间戳 / 预算 / selected / deferred / dropped / tokens_used
            

Three things must be changed for real deployment: replace the token estimate with a real tokenizer (len // 4 has a large error for Chinese); supplement error detection with domain-specific keywords; and the TriageDecision must land in ELK or Datadog, with the dropped_count trend reviewed daily.

Enterprise deployment example

A regional bank's loan-review Agent ran accurately on standard consumer loans (8 documents). Then a commercial loan application piled in 43 documents, the context would not hold them, and the Agent sorted by filename and made a single naive truncation. The pile it cut included a 2024 collateral valuation report, and the pile it kept included a 2019 photo of a business registration that had long since expired. The Agent, looking at the "complete set" that remained, recommended approval, and two weeks later the loan went into default. The rewrite switched to four-level triage: strong evidence such as the collateral valuation and the current financial statements went to P0/P1, the historical registration was downgraded by time decay, and all "anomaly/missing" markers were force-protected from being dropped. The root cause was not weak reasoning; it was that the Agent had not been taught who should come through the door first.

Relationship to other patterns

• Semantic Compression (P2): Complementary and often paired. Triage governs "which information enters context" (future tokens), and compression governs "how what has already entered is compressed without losing the key parts" (past tokens). The P2-level "loaded after compression" is exactly where the two connect.
• Progressive Discovery (P3): Naturally coupled. The P3 handle from triage is precisely the object that progressive discovery pulls on demand—one is selected passively, the other is sought actively.
• Layered Memory (Memory module): Shares the same handle-naming convention, but with different TTLs. Handles for code and documents always point to the current version and belong to triage; handles for user preferences and conversation state evolve through versions and belong to memory. It is recommended to mark P3 handles in two classes, immutable:// and versioned://.

What this pattern teaches

Context triage is not prompt tuning; it is an echo of operating-system process scheduling in the LLM era—the context window is scarce CPU time, and the triage algorithm is the scheduler that keeps the most important process from being starved.

This page is part of the ADPS pattern white papers. Back to the pattern matrix, or see the runnable code catalog.