aiwg/agentic/code/addons/aiwg-utils/rules/context-bloat.md

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

# Context-Bloat Antipattern

**Enforcement Level**: MEDIUM
**Scope**: All tool-using agents across all platforms
**Addon**: aiwg-utils (core, universal)
**Issue**: #648

## Overview

Context-bloat occurs when an orchestrator passes excessive, unrequested context to a sub-agent. The sub-agent receives full conversation histories, entire file trees, or comprehensive background documentation when it only needs a focused slice. Bloated context degrades output quality, wastes tokens, and often causes the agent to address the wrong portions of its input.

This rule provides a cost-focused angle on the broader scoping concerns in `subagent-scoping.md`. Where subagent-scoping focuses on task scope, context-bloat focuses specifically on the information passed with that task.

## Problem Statement

Context-bloat arises from:
- Forwarding the entire parent conversation history to a sub-agent
- Passing all files in a module when the agent only touches one
- Including full project documentation when the agent needs a single fact
- Pre-loading "background" the agent didn't ask for

This causes:
- Token waste and increased cost per call
- Agent attention diluted across irrelevant context
- Earlier, relevant parts of context displaced by later irrelevant additions
- Hallucination risk increases as the agent pattern-matches against noise

## Mandatory Rules

### Rule 1: Pass File Paths, Not File Contents (When Agent Will Read Itself)

When a sub-agent will read files as part of its task, pass the path — not the content.

**FORBIDDEN**:
```
Sub-agent prompt:
  Here is the full content of auth.ts (2,400 tokens):
  [entire file]

  Here is the full content of userService.ts (3,100 tokens):
  [entire file]

  Task: Check if validateEmail() handles null input.
```

**REQUIRED**:
```
Sub-agent prompt:
  File: src/auth/validators.ts
  Function: validateEmail()
  Task: Verify null input handling. Read the function directly.
```

### Rule 2: Conversation History Is Almost Never Needed

Sub-agents rarely need the parent session's conversation history. They need facts, not narrative.

**FORBIDDEN**:
```
Sub-agent prompt:
  [50 messages of parent conversation history...]
  Based on all of the above, please check if the tests pass.
```

**REQUIRED**:
```
Sub-agent prompt:
  Context: Refactoring auth module. Tests were green before changes.
  Task: Run npm test and report which tests fail, with error messages.
```

### Rule 3: Limit Background to What the Task Actually Uses

Before including background documentation, ask: "Will the agent's output change if I remove this?" If no, remove it.

**FORBIDDEN**:
```
Sub-agent prompt:
  [Full project architecture document]
  [Full requirements spec]
  [Team profile]
  Task: Fix the null pointer in userService.ts line 42.
```

**REQUIRED**:
```
Sub-agent prompt:
  File: src/services/userService.ts, line 42 (null pointer exception)
  Error: TypeError: Cannot read property 'id' of undefined
  Task: Fix the null pointer. The user object may be undefined — add a guard.
```

### Rule 4: Context Budget Review Before Dispatch

Before dispatching a sub-agent, estimate its context size. If >50% of available context window is background rather than task-critical information, trim aggressively.

| Content Type | Include? | Trim to |
|-------------|----------|---------|
| Task description | Always | Full |
| Relevant code (agent will modify) | Always | Relevant sections only |
| Error messages | Always | Full |
| Related files (agent won't modify) | Rarely | File paths only |
| Project background | Only if load-bearing | Key facts, not documents |
| Conversation history | Almost never | Summary sentence |
| Entire module contents | Never | Specific function/section |

## Detection Patterns

| Symptom | Likely Cause |
|---------|-------------|
| Sub-agent addresses wrong section of input | Attention diluted by context-bloat |
| Sub-agent cost is 5-10× expected | Context far larger than task |
| Sub-agent output summarizes context instead of doing the task | Overwhelmed by input volume |
| Sub-agent references irrelevant prior conversation | History forwarded unnecessarily |

## Integration with Other Rules

- **subagent-scoping**: This rule addresses context quantity; subagent-scoping addresses task scope
- **context-budget**: Context-bloat directly wastes the budget allocated per sub-agent call
- **implicit-dependencies**: The inverse failure — passing too little explicit context (see `implicit-dependencies.md`)

## References

- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/subagent-scoping.md
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/context-budget.md
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/implicit-dependencies.md
- OpenProse antipatterns guidance (research: #617)

---

**Rule Status**: ACTIVE
**Last Updated**: 2026-04-02