optimal-context

name

optimal-context

description

Context-engineering workflow for non-trivial coding work — building a new feature or project, fixing/finishing a PR, refactoring, debugging, or implementing any change in a real or large codebase where an agent tends to lose the plot as its context window fills. Use it to keep output quality high on big tasks: it runs Research → Plan → (gate the plan) → Implement, holds context in the 40–60% "smart zone" and compacts at the 60% "smart/dumb line", and reviews the plan before any code is written. Integrates the Glassbox tools (context HUD, Plan-Gate, autopilot tool-output curation, auto-compaction) when that repo is available; otherwise applies the same practices by hand. Trigger on "implement X", "build this", "fix this PR", "add a feature", "refactor", or any multi-step change where correctness in a sizable codebase matters.

Optimal Context

A disciplined workflow for getting correct, low-rework results from a coding agent on non-trivial tasks. Its one premise (from HumanLayer's ACE-FCA): the context window is the only lever on output quality — so spend it deliberately. Don't out-spawn agents; engineer the one that's running.

Use this for: new features, new projects, finishing/fixing a PR, refactors, and debugging in real/large codebases. Skip it for one-line edits or pure Q&A.

The five rules (internalize these)

1. Context is the only lever. Wrong info in context is worse than missing info. Keep what's loaded correct, complete, and small.
2. Stay in the smart zone. Target 40–60% context utilization. Past 60% — the "smart/dumb line" — quality degrades; compact instead of pushing on.
3. Review highest up the pipeline. A bad line of research → thousands of bad code lines; a bad line of plan → hundreds. Put the most scrutiny on research and the plan, not the diff.
4. One loop, one step. Do one verifiable thing, gate it (tests/types/build), commit, repeat. Bound the work; don't coax the model to "keep going."
5. Code is disposable; the plan/spec is durable. Iterate on the plan (cheap) before generating code (expensive and trajectory-locking).

The workflow

1. Research (highest leverage — over-invest)

Map the relevant code before proposing anything. Use sub-agents / search to find files and trace flow without dumping everything into the main context. Write a short research.md: current state, the few files that matter, constraints, open questions. Have a human (or a second agent) sanity- check the research before planning.

2. Plan

Write a tight plan.md (~200 lines max): overview, then phases where each phase is one verifiable milestone with explicit files to touch and how you'll test it. Keep it small enough to re-read.

3. Gate the plan (before any code)

Adversarially review the plan against five checks — architectural misunderstanding · missing/wrong files · untested assumptions · phasing/granularity · "one bad line → 100 bad lines" risks.

• With Glassbox: bun run gate plan.md → structured verdict + a decision (auto-pass / auto-block → revise / escalate → ask a human). Only involve a human when the gate isn't confident.
• Without it: do the same review by hand or with a second agent; fix the plan, don't proceed on a shaky one.

4. Implement (bounded loops, watch context)

Execute the plan one phase at a time. After each phase: run tests/types/build, commit, update the plan's status. Watch utilization — with Glassbox, run the agent under the HUD (bun run hud "<task>" or the web HUD bun run serve) and respect the nudge at the smart/dumb line.

5. Compact at the line (don't drown)

When context crosses ~60%, intentionally compact: distill progress into the plan/a brief, then continue from the distilled state (a fresh session if needed) so you resume lean instead of degrading. With Glassbox this is automatic: bun run autocompact "<task>" forks a fresh session seeded with a continuation brief + completed-set when the line is crossed. Also enable --autopilot (optionally --summarize) to auto-curate fat tool/MCP outputs before they cost context.

Applying it to the three common jobs

• New feature / project: run the full loop. Research the surrounding code first; gate the plan; implement phase-by-phase with tests; compact at the line. The plan + research + commits are your receipts.
• Fix / finish a PR: Research = read the PR diff, its linked issue, the failing checks, and the surrounding code. Plan the minimal correct change. Gate it (does it address root cause? does it break callers? are tests covering it?). Implement in small commits; keep the PR scope tight.
• Implement any change in a big repo: the danger zone for context. Lead with research sub-agents so the main context stays lean, gate the plan hard (big repos punish wrong assumptions), and lean on auto-compaction so a long task doesn't drown the window.

Anti-patterns (don't)

• Fan out dozens of agents for spectacle. Restraint + context discipline beats parallelism here.
• Dump whole files / huge tool outputs into context "just in case." Curate.
• Review only the final diff. By then the leverage is gone.
• Push past 60% to "finish" — that's exactly when output quality drops.

When Glassbox is present

Commands: bun run gate <plan.md> (confidence-gated plan review), bun run hud "<task>" / bun run serve (context HUD), bun run autocompact "<task>" (auto-compaction), --autopilot[ --summarize] (tool-output curation), bun run rework-eval / brief-eval (metrics). See the repo's README and AUTOPILOT.md. If Glassbox isn't available, the rules and workflow above stand on their own — they're practices, not just tooling.

See reference/playbooks.md for step-by-step playbooks per job type.