ttttmr/pi-context/context-management

Context Management

Use this skill to keep the active conversation as a useful working set for the next step. Keep raw only the context that still needs direct reasoning; carry the rest as compact task state when that is more efficient.

Core rhythm:

• checkpoint before mess
• review timeline when structure affects the next decision
• compact when a state summary is a better working set than the raw trail

Use only these tools:

• context_checkpoint
• context_timeline
• context_compact

Working-set model

Before choosing a tool, ask:

• What am I trying to do next?
• What facts, constraints, or artifacts must stay raw for that next action?
• What important data has a reliable external source I can re-check instead of carrying raw?
• What history is useful only as a conclusion, pointer, or state update?
• What history is process noise or stale baggage?

Classify context into:

• Raw context: user intent, constraints, code/log/error details, evidence, or plan text you expect to inspect directly soon.
• State summary: decisions, findings, lessons, changed files, validation status, source pointers, rejected leads, and next steps that can replace raw process.
• Discardable process: repetitive searches, verbose logs, abandoned hypotheses, false starts, and unrelated turns whose useful value is already captured or gone.

If the active context is already small, coherent, and directly useful for the next step, do not manage it just to be tidy.

When to use

Use this mode when the work may outgrow one clean thread:

• search, research, browser work, or reading many files/logs/pages/results
• investigate -> decide -> execute -> validate
• plan -> implement -> verify
• background or asynchronous work, handoffs, user decisions, or delayed results
• multiple approaches, retries, failed branches, comparisons, or pivots
• repeated similar cases, tickets, reviews, or batch items
• a main task that may be interrupted by side tasks
• repeated progress/status checks that indicate active state is hard to track
• scattered threads that need cleanup before continuing
• debugging, troubleshooting, refactoring, migration, or code-facing work that may get noisy

If one of these clearly applies, take a structural action now, usually a checkpoint. Do not merely describe the workflow. If the user has not provided enough task details, still checkpoint the workflow shape before asking clarifying questions.

Usually skip this skill for one-shot reads, bounded summaries, direct rewrites, simple lookups, deterministic scripts, short tasks that can stay clean, or moments where the active context is already a good working set.

Start-of-turn check

At the start of each new user message, classify it:

• Same task / next phase: evaluate the compact gate; keep recent raw material when the next phase still needs it.
• Correction, review, or feedback on recent work: answer from the raw recent context; do not compact merely to respond. Questions about implementation choices, shortcuts, trade-offs, or known risks are exactly why the completed work should remain inspectable.
• New task, explicit next step, or direction shift: evaluate whether removing the completed noisy segment would help the now-known work after recovery costs. Inspect timeline when anchors are unclear; a new task alone does not require compaction.

Checkpoint marks anchors and timeline shows structure. When the compact gate passes, compact continues from the chosen continuation anchor with a summary of what happened after it. These are available choices, not a required pipeline. The target is a working-set choice, not an age choice.

Main loop

1. Before noisy work, create a semantic checkpoint as the first context-management action. If the first job is orientation over existing history, run context_timeline before adding a new checkpoint.
2. When the task shape is clear, read one matching scenario reference only if it will change tool timing, anchor choice, or summary content. Skip reference loading for obvious short applications where this main skill body is enough.
3. Add checkpoints at meaningful milestones: phase boundaries, risky attempts, reusable batch methods, and interruptions.
4. Use context_timeline when the active path structure affects the next decision or compact target.
5. At continuation boundaries, run the compact gate before starting another known phase. If the whole requested task is complete, present the result and wait for feedback; delivery and a request for feedback are not themselves a continuation.
6. After a successful compact, continue from the injected summary instead of dragging the full raw path forward.

Continuation boundaries

A continuation boundary is a point where the current phase has produced a stable result and the next action will use that result to start a different phase. It is not necessarily the end of the user's whole task.

Examples: investigation -> decision/plan/implementation, implementation -> validation, failed validation -> next approach, delayed result -> routing/action, received user decision -> execution, rejected branch -> replacement direction, side request -> pause/summarize mainline before switching.

A phase boundary is a chance to evaluate compaction, not a reason to compact. A stable conclusion does not make the code, tests, logs, or evidence supporting the next action obsolete. Diagnosis -> fix and implementation -> validation often share the same raw working set.

A response that presents completed work and asks the user for review, feedback, or a decision is not a continuation boundary: the next work is unknown, and the user may ask about details from the raw trail. Deliver the result and wait without compacting. Once feedback or an explicit next task arrives, decide whether the resulting known continuation benefits from compaction.

An actual handoff to a known next actor, process, validation, or queued phase can be a boundary when the next action is defined and needs only stable state. Do not treat a merely possible later user response as that kind of handoff.

Read the right reference

Read one primary reference only when the scenario pattern will affect tool timing, anchor choice, or summary content:

• search / research / reading-heavy work -> references/search-research-and-reading.md
• development / debugging / troubleshooting / refactoring / migration -> references/development-and-troubleshooting.md
• planning / staged execution / todo-driven work -> references/planning-and-execution.md
• repeated similar items / batch work -> references/repeated-items-and-batch-work.md
• task switching / pause-resume / interruptions / cleanup-and-continue -> references/task-switching-and-cleanup.md
• interleaved async work / overlapping fronts / background results / user decisions -> references/interleaved-async-work.md

Also read references/retry-branch-and-pivot.md when multiple approaches, failed branches, comparisons, retries, or pivots become central.

Tool policy

context_checkpoint

Use before noisy work, a new phase, a risky attempt, switching subtasks, or after a meaningful milestone. Record actual task changes with a unique `<scope>-<phase>` name:

Keep scope identical for related markers, such as parser-investigation-start and parser-investigation-done. Use a different scope for a different phase, such as parser-validation-start. Names must remain unique; use an attempt/cycle qualifier before the suffix when repeating work. Timeline shows the parsed phase next to the label but does not infer relationships between differently qualified names. Other names remain valid ordinary anchors.

Recognizing a meaningful new task, stable result, pivot, interruption, or resumption should lead to the corresponding checkpoint—not just a prose description. Do not mark every message or minor action. Avoid generic names like start, checkpoint-1, or retry.

Interpreting phase markers

Phase markers are your own declarations, not a tracked state machine; timeline displays them verbatim. Use the sequence to reflect on what actually happened:

• New task / `done → start`: a known continuation may now benefit from summarizing the completed raw trail. Apply the compact gate before accumulating the next noisy phase.
• Stable result / `done`: check what was settled and what happens next. If the requested work is complete and you are awaiting feedback, deliver and wait; do not compact just because you marked it done.
• Consecutive `start` markers: distinguish a nested subtask, retry, task switch, or an omitted status marker. Do not assume the previous task is finished or abandoned. Mark a real pause/pivot if appropriate, not to repair an artificial state machine.
• `pivot`: identify the rejected approach, reusable evidence, lesson, and replacement direction. Compact only if these form stable state for a known continuation.
• `pause → resume`: restore the goal, constraints, and pending work; check whether intervening work is now baggage. Pausing for feedback itself is not a compact boundary.

Timeline intervals show historical content estimates, not exact active-model occupancy or reclaimable tokens. When orientation or target choice is unclear, inspect timeline. Choose the smallest sufficient working set, not automatically the most recent checkpoint. Preserve decisions, external effects, verification state, and the known next step in any compact summary.

context_timeline

Use it as the structural view of the active path:

• when the current path shape affects the next decision
• when several checkpoints, branches, or task switches exist
• before choosing a non-obvious compact target
• when the thread feels cluttered and you need to distinguish useful context from baggage

When reading the timeline, ask which raw messages are still needed for the immediate next action, which paths are now baggage, and which anchor gives the most useful working set after summary injection and recovery.

context_compact

Use it to replace raw history with a state summary when the next phase would benefit from a smaller working set.

Typical points to evaluate the compact gate: investigation -> execution, diagnosis -> fix, implementation -> validation, failed attempt -> next attempt, representative item -> remaining batch, completed noisy task -> a newly received user task. None requires compaction by its phase name alone.

Strong signals to consider compaction:

• repeated progress/status checks
• inability to summarize current state, next action, and open risks in one short paragraph
• rejected, abandoned, or superseded branches
• stable result after many tool calls or long output
• returned background/asynchronous/delegated result
• material plan or approach change
• side question arriving while stale process history is active

Do not compact while exploration is still active, when the result is unstable, just because the skill triggered, or just because the user-visible task ended.

Compact gate

Before calling context_compact, require all four: