manage-context

Manage Context

Recovery-phase skill. Keep work stable when context grows long, the codebase is unfamiliar, attention drifts, or the model is stuck. Combines context budget, session hygiene, zoom-out, deep triage, escalate, and onboarding.

Iron Rule

1. NEVER continue editing when the same bug surfaces from 3+ angles — that is a context loss signal. Zoom out first. 2. NEVER assume a fact from earlier in the session is still valid for files that have been edited since. Re-read before acting. 3. ESCALATE to a stronger model (or a fresh session) before the third failed attempt at the same goal, not after the tenth. 4. ONBOARDING in an unfamiliar repo: detect stack and conventions from real files before writing a single line.

When to use

• Context window is past ~60-80% used (or context bar yellow/red) — exact tokens depend on the model's window; modern windows range from 200k to 1M+, so use ratio, not absolute
• The same bug keeps reappearing at a different surface
• You forgot a constraint the user stated earlier
• You are starting in an unfamiliar codebase
• A multi-file refactor is fanning out beyond the plan
• The current model is stuck on architecture or root cause
• The previous attempt produced a wrong fix that almost looked right

Boundary

Owns:

• Context recovery, constraint re-read, session hygiene, zoom-out, onboarding, escalation.

Does not own:

• Product scope decisions.
• Implementation edits.
• Final verification or branch fate.

Return / hand off:

• After recovery, route back through using-rolepod or the current phase skill.
• If still stuck after recovery, escalate the model / session instead of widening scope.

Inputs to gather

• The user's original request (literal quote if possible)
• The current state of the work (last commit, files staged, tests green / red)
• The constraint set the user stated (deadline, no-touch zones, style)
• Available context-trim commands for your CLI (see references/cli-fallbacks.md)

Workflow

1. Detect the failure mode

Symptom	Mode
Context window past ~60-80% (or bar yellow/red)	Context budget
Forgot a stated constraint	Session hygiene
Same bug at 3 surfaces	Zoom-out
3+ failed fix attempts on the same target	Escalate
Multi-file edits beyond the plan	Deep triage
Unfamiliar repo, no clear entry point	Onboarding

2. Context budget

If context is heavy:

• /compact <focus> — keep the relevant work, drop the rest
• /clear — start fresh between unrelated tasks
• /rewind — undo a recent path you regret
• claude --continue after /rename to switch session focus

These are Claude commands; for the Codex / Gemini equivalents see references/cli-fallbacks.md.

Only load what the current task actually needs. Tier 1 skills + the touched files is usually enough.

Starting fresh instead of /compact → fill templates/handoff-brief.md so the next session resumes without re-asking. The brief, not the CLI command, is what makes work resumable.

3. Session hygiene

Re-read the original request literally. List the constraints still in force. Verify the touched files match what you remember; they may have changed since you last read them.

4. Zoom-out

Step back from the immediate edit. Ask: what is the user actually trying to accomplish? Is the current path of attempts still aligned with that goal, or have you started solving a sub-problem you invented?

5. Deep triage (multi-file)

Map the actual surface: list every file you have edited or planned to edit. Group by concern. Re-check the plan against the spec. If the surface is wider than the plan, write a new plan, do not keep widening edits.

6. Escalate

If stuck after multiple attempts:

• Capture the exact problem (error, what was tried, what failed)
• Surface the blocker to the user with a concrete ask, or start a fresh session with the captured context
• Resume with the user's direction, not another blind attempt

Three failed attempts is the trigger. Do not "try one more thing" past that.

7. Onboarding (new repo)

Before any edit:

• Read README.md, CLAUDE.md if present
• Detect stack from package.json / pyproject.toml / Cargo.toml / Makefile
• Read 2-3 representative files to match style
• Find the test runner and run a smoke test
• Identify the entry point and the main module

If a matching Rolepod agent is available

Delegate the recovery action to the closest specialist:

• system-architect for multi-file refactor scope decisions
• qa-tester when the recurring failure is in test discipline
• universal-reviewer to read your in-flight diff with fresh context

Brief: original user request, what has been tried, what failed, what you suspect is wrong.

If no matching agent is available

Execute as Lead with this minimum viable checklist:

1. Re-read the original user request literally
2. List the constraints still in force
3. List the files you have actually touched vs the plan
4. Identify which of the six modes above matches the current symptom
5. Run the appropriate context command for your CLI (see references/cli-fallbacks.md)
6. For unfamiliar repo: read README + config + 2-3 representative files before editing
7. For stuck: capture exact failure and ask the user for direction
8. For multi-file drift: stop, write the new plan, then continue

Output format

Mode: <context budget | session hygiene | zoom-out | escalate | triage | onboarding>
Trigger: <what tipped this skill>
Action taken: <command run / re-read / escalation>
State after: <what is loaded, what is dropped>
Next: <which skill resumes work>

When starting a fresh session, the durable artifact is templates/handoff-brief.md.

Examples

Non-blocking — read only when unsure how to recover or hand off:

• examples/context-examples.md — a zoom-out recovery and a session handoff, each a good/bad pair with a "why good wins" table. Read the whole file; the contrast is the lesson.

References

Load only when the task needs it:

• references/cli-fallbacks.md — context-management commands per CLI (Claude / Codex / Gemini)

Hard stops

• Context is too heavy to trim safely → start a fresh session with a written handoff brief
• 3 failed attempts at the same target → stop, escalate, do not try a fourth blind
• You cannot name what the user asked for in one sentence → stop, re-read the request
• An unfamiliar repo has no README and no obvious entry → ask the user before editing

Full Rolepod enhancement

Full Rolepod improves this phase by surfacing context-budget reminders via SessionStart hooks (where the CLI supports them), the escalation pattern, the deep triage checklist, and onboarding on first session in a new repo.

Next phase

• After recovery, return to the phase you came from — write-spec, write-plan, implement-plan, debug-issue, check-work, review-code, finish-work, or simplify-code.
• If still stuck after recovery, surface the blocker to the user with a concrete ask.