@duckmind/dm-windows-x64 0.63.4 → 0.63.6

package/extensions/dm-context/skills/context-management/references/development-and-troubleshooting.md

@@ -0,0 +1,75 @@
+# Development and Troubleshooting
+
+Use this reference for long-running:
+- implementation
+- debugging
+- troubleshooting
+- refactoring
+- migration
+- review or audit work
+
+These tasks often stay cleaner when treated as stages with anchors, instead of one uninterrupted thread. If multiple alternative approaches, failed branches, or route comparisons become central, also read `retry-branch-and-pivot.md`.
+
+## Working pattern
+
+1. Create a checkpoint before starting serious work.
+2. Add checkpoints before risky edits, new approaches, or major phase changes.
+3. Review the timeline when you need to understand the current shape of the work.
+4. Compact after a stable implementation milestone, a failed approach, or a completed troubleshooting phase when there is another known phase, attempt, validation step, or task switch that benefits from cleanup. If files, processes, or external systems changed, include those side effects in the summary because context navigation does not roll them back. If the completed phase is the final user-visible deliverable, present it and wait for feedback or the next instruction; do not compact merely because you asked for review.
+
+## Typical checkpoint moments
+
+Checkpoint:
+- before starting implementation
+- before a risky refactor
+- before trying an alternative fix
+- after a milestone like "root cause confirmed" or "first pass implemented"
+- before switching to a side task
+
+Example checkpoint names:
+- `parser-fix-start`
+- `cache-refactor-attempt-2`
+- `migration-plan-ready`
+- `incident-root-cause-confirmed`
+
+## Timeline review moments
+
+Run `context_timeline` when:
+- multiple attempts now exist
+- the task moved from diagnosis to implementation
+- you are about to abandon one approach and restart from another anchor
+- you are unsure which checkpoint best represents the clean continuation point
+
+## Compact patterns
+
+### After a failed attempt
+
+Use compact when an attempt clearly failed and you have a crisp summary of why.
+
+```javascript
+context_compact({
+  target: "memory-leak-fix-start",
+  summary: "Current task: continue the memory leak fix. State: WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Decision: abandon WeakRef and try object pooling. Next step: implement the object-pooling approach.",
+  backupCheckpoint: "memory-leak-weakref-raw-history"
+});
+```
+
+### After a completed phase
+
+Use compact when a phase is done and a known next phase would work better from a focused state summary than from the raw implementation/debugging trail. Do not use this as a reflexive final step before or after delivering finished work: preserve the raw trail while awaiting review, feedback, or a decision. Compact only when validation, a next phase, a next attempt, or a newly received user task makes the continuation concrete.
+
+```javascript
+context_compact({
+  target: "parser-fix-start",
+  summary: "Current task: validate the parser fix. State: implementation is done and the debugging trail can be summarized. External state: parser implementation and related tests were changed on disk; context navigation did not revert them. Validation not yet run after final edit. Next step: run targeted validation and summarize remaining edge cases.",
+  backupCheckpoint: "parser-fix-debug-history"
+});
+```
+
+## Warning signs
+
+Switch into stronger context-management behavior when:
+- you are accumulating many partial theories
+- the thread contains multiple fix attempts
+- you keep revisiting earlier reasoning
+- the next step is clear but the path behind it is getting noisy

package/extensions/dm-context/skills/context-management/references/interleaved-async-work.md

@@ -0,0 +1,143 @@
+# Interleaved Async Work
+
+Use this reference when the hard part is **not** the external worker itself, but the current agent carrying several overlapping lines of work in one conversation.
+
+Common examples:
+
+- a main task continues while background jobs, subagents, reviewers, or tools may return later
+- the user asks side questions while another front is still active
+- progress updates, returned results, decisions, and new work are interleaved in the same thread
+- several pending fronts have different next actions, and raw history starts making the current state hard to see
+
+This is context management for the current agent. It is not a subagent-management policy. The goal is to keep the current working set clear enough to answer: **what am I doing now, what is parked, what just returned, and what raw context is still needed?**
+
+## Mental model: fronts
+
+Treat each overlapping line of work as a **front**.
+
+A front may be:
+
+- the current user-facing task
+- a paused mainline task
+- a background command or long-running job
+- a subagent/reviewer/collaborator result that may return later
+- a pending user decision
+- a side request that should be answered before resuming the mainline
+
+For each front, keep only one of these in the active working set:
+
+- **Active raw front:** the thing you are reasoning about right now; keep necessary raw details.
+- **Parked state capsule:** a paused or waiting front summarized by goal, current state, source pointers, next action, and blockers.
+- **Stale process:** old logs, retries, status chatter, and abandoned paths whose lesson has already been captured.
+
+The mistake to avoid is carrying every front raw at once.
+
+## Working pattern
+
+1. Identify the active front before each substantial reply or tool call.
+2. If another front is still pending, keep it as a small state capsule rather than raw history.
+3. When a result returns, capture it into the relevant front before responding.
+4. If the returned result does not become the active front immediately, park it as state and preserve the user's current focus.
+5. Before switching fronts, compact if the old front's raw process is now stale and the next front can continue from a summary.
+6. If several fronts are tangled, run `context_timeline` to find the clean anchor and separate active, parked, completed, and stale paths.
+
+## What to record per parked front
+
+Use a short capsule:
+
+- Front: short name for this line of work
+- Goal: what this front is trying to accomplish
+- State: waiting / running / returned / blocked / ready for next phase
+- Latest stable result: what is known now
+- Source pointers: files, links, task ids, log paths, branches, records, queries, or commands that identify where to re-check details
+- Decisions and constraints: choices already made that still matter
+- Rejected paths: approaches that should not be repeated
+- Pending input or trigger: what would make this front active again
+- Next action: what to do when resuming this front
+
+This capsule is for future-you, not for the external worker. It should be enough to resume without rereading the interleaved raw thread.
+
+If a front's detailed state is available from a reliable external source, keep the pointer, not the dump. For example, store the task id plus the command/log path to inspect it, not pages of status output; store the database query or record id, not every row; store the file path and relevant section, not the whole file. Copy raw details only when they are small, volatile, hard to retrieve, or needed for immediate reasoning.
+
+## When to compact
+
+Compact when interleaving has made raw context a worse working set:
+
+- you are switching from one front to another after a noisy phase
+- a side request arrives while the mainline is noisy but resumable from a capsule
+- a background/subagent/reviewer/tool result returned and its raw logs are no longer needed
+- the user has asked for status more than once and you cannot state all active fronts briefly
+- a front was rejected, superseded, completed, or parked indefinitely
+- the next action belongs to a different front than the recent raw history
+- the active front started much earlier, and the middle of the thread is mostly completed or unrelated fronts
+
+Do **not** compact just because async work exists. Compact when a front can safely be represented as state while another front becomes active.
+
+## Choosing how far back to compact
+
+Interleaved work often makes recent anchors poor targets: they may preserve the completed fronts that happened after the active front was launched. Be willing to compact aggressively when the summary can restore state.
+
+A compact to an old anchor or even `root` is appropriate when:
+
+- the active front can be described by a concise capsule
+- completed fronts between the anchor and now no longer need raw context
+- important details are recoverable from reliable source pointers
+- the next action does not require inspecting the interleaved raw discussion
+- you can name what remains active, what is parked, and what is done
+
+Use a backup checkpoint for safety when the interleaved raw path may still matter, but do not keep it active just because it is long.
+
+Before a deep compact, ask:
+
+```text
+Active now: which front am I resuming?
+Parked: which fronts still wait for input/result?
+Done: which fronts can be summarized or omitted?
+Pointers: where can I re-check authoritative details?
+Next: what is the immediate action after compacting?
+```
+
+## Handling returned results
+
+When a delayed result appears in the middle of another thread:
+
+1. **Capture:** identify which front it belongs to and summarize its result.
+2. **Classify:** progress, stable completion, failure, decision needed, or noise.
+3. **Choose focus:** decide whether this result should interrupt the current active front. If not, park it.
+4. **Compact if needed:** if switching to it or away from it would drag stale logs/retries forward, compact first.
+5. **Continue:** resume the chosen active front from a clean working set.
+
+## Example capsules
+
+```text
+Front: import-test-flake
+Goal: fix flaky import tests.
+State: reviewer returned findings.
+Latest stable result: fixed sleeps were rejected; signed retry strategy is still viable.
+Source pointers: branch retry-import-tests, log tmp/import-flake.log.
+Pending input or trigger: decide whether to implement bounded retries.
+Next action: if accepted, implement bounded retry and rerun targeted tests.
+```
+
+```text
+Front: docs-build
+Goal: validate generated documentation before publishing.
+State: background build running.
+Latest stable result: source edits complete; validation not yet known.
+Source pointers: task docs-build, output dist/docs/.
+Pending input or trigger: build exit status.
+Next action: on success, summarize validation; on failure, inspect first build/link error.
+```
+
+## Common mistakes
+
+Avoid:
+
+- treating async/subagent management as the goal instead of keeping the current agent's working set clear
+- carrying several fronts raw at once
+- copying externally recoverable status dumps instead of preserving reliable source pointers
+- letting a returned result overwrite the user's current active request without deciding focus
+- reporting status repeatedly while the real problem is that fronts are not summarized
+- compacting away a front without preserving how to resume it
+- avoiding a deep compact even though source pointers and capsules can restore the active state
+- resuming from memory when a small front capsule would be safer

package/extensions/dm-context/skills/context-management/references/planning-and-execution.md

@@ -0,0 +1,81 @@
+# Planning and Execution
+
+Use this reference when the work is organized around an explicit execution frame, such as:
+- a formal implementation or migration plan
+- a roadmap with multiple milestones
+- a lightweight todo list or checklist
+- staged execution that will be revisited, updated, or reordered across many turns
+
+The defining feature here is not just that the work has phases. It is that execution repeatedly returns to an explicit plan, roadmap, or todo baseline.
+
+## Two common variants
+
+### Formal plan
+Examples:
+- a plan produced by a planning step or planning agent
+- a migration plan with several services or phases
+- a rollout plan with checkpoints and validation steps
+
+### Lightweight todo / checklist
+Examples:
+- a short task list for a refactor
+- a checklist for a release or audit
+- a small execution outline that will be worked through item by item
+
+Both variants use the same context-management rhythm.
+
+## Working pattern
+
+1. Create or confirm the plan / todo list.
+2. Create a checkpoint for the clean plan-ready state.
+3. Execute one subtask or phase.
+4. If that subtask becomes noisy, let it get noisy locally.
+5. Once the subtask produces a stable takeaway and another subtask or phase remains, compact to the anchor that gives the next subtask the cleanest sufficient working set, often the plan-ready or phase-start anchor.
+6. Continue with the next subtask from that focused working set.
+7. If the plan changes materially, checkpoint the updated plan state again.
+8. If the last subtask completes the user's whole request, give the final answer without an automatic compact and retain the raw trail for review or feedback. Decide on cleanup only when a later message establishes a new task or explicit next phase.
+
+## Useful anchors
+
+Example checkpoint names:
+- `auth-migration-plan-ready`
+- `release-rollout-plan-ready`
+- `parser-refactor-todo-baseline`
+- `cleanup-phase-2-start`
+- `vendor-audit-milestone-1`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- several subtasks have already been executed
+- the plan has changed more than once
+- multiple branches now exist under the same plan
+- you are unsure whether the next subtask needs the overall plan, the current phase context, or only a summary
+
+## When to compact
+
+Compact when:
+- a subtask is complete, another subtask remains, and its raw execution path is no longer worth keeping active
+- a phase finished and the next phase should start from a cleaner state
+- the plan remains valid but the current execution segment has become noisy
+- a later user message starts a new task after the plan-driven task completed noisily
+
+Do not compact just because a todo list exists. Compact when a specific execution segment has already served its purpose and can be compacted for an actual continuation. If the segment changed files, launched/stopped processes, or updated external systems, record those side effects in the summary; context navigation does not revert them.
+
+## Replan
+
+If the plan itself changes materially:
+1. finish or abandon the current noisy segment
+2. summarize the change in direction
+3. checkpoint the new plan-ready state
+4. continue from the updated plan anchor
+
+If the plan change is driven by failed branches or strategy shifts, also read `retry-branch-and-pivot.md`.
+
+## Common mistakes
+
+Avoid:
+- keeping every finished subtask's raw reasoning active instead of preserving only the reusable state
+- choosing an anchor that drops the current plan state without preserving it in the summary
+- failing to checkpoint the updated plan after a major replan
+- confusing repeated-item work with plan-driven work when the subtasks are actually different in nature

package/extensions/dm-context/skills/context-management/references/repeated-items-and-batch-work.md

@@ -0,0 +1,69 @@
+# Repeated Items and Batch Work
+
+Use this reference when the work involves many similar items handled over many turns, such as:
+- repeated cases
+- repeated tickets
+- repeated reviews
+- repeated checks
+- repeated fix attempts on similar inputs
+
+Use this reference when the items are similar enough that the same method should be reused across them. If the subtasks are heterogeneous and anchored to a roadmap or todo baseline, use `planning-and-execution.md` instead.
+
+## Working pattern
+
+1. Create a checkpoint at the start of the overall repeated-item task.
+2. If item 1 teaches you a reusable approach, checkpoint again after that approach becomes clear.
+3. Work item by item.
+4. Compact after each completed item or completed mini-phase when another item remains and the raw path is no longer worth carrying forward.
+5. Use timeline occasionally to verify that the history still has a clean structure.
+
+For repeated-item work, the default between-item move is not "keep carrying the last item's raw reasoning". Once an item is done, its takeaway is stable, and another item remains, compact to the repeated-work anchor or other baseline that preserves the reusable method without item-specific noise. If the last item completes the whole user request, deliver the final answer and retain the raw trail for review or feedback; decide whether to compact only after a later message establishes new work or an explicit next phase.
+
+## Useful anchors
+
+Example checkpoint names:
+- `vendor-review-start`
+- `vendor-review-method-clear`
+- `ticket-triage-batch-start`
+- `ticket-triage-pattern-1-confirmed`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- several items have already been processed
+- item-level work has created multiple branches or compactions
+- you want to confirm that the overall pattern still looks clean
+- you are about to choose which anchor repeated work should keep returning to
+
+## When to compact
+
+Compact after:
+- a representative item produced a reusable method and the batch will continue
+- a single item is complete, another item remains, and the raw path should be compacted
+- an item-specific dead end is understood and should not remain active in full
+- a new user message arrives after the batch completed, and the batch's raw path is stale baggage for the new task
+
+## Example rhythm
+
+```javascript
+context_checkpoint({ name: "vendor-review-start" });
+
+// ... work through first representative item ...
+
+context_checkpoint({ name: "vendor-review-method-clear" });
+
+// ... process another item ...
+
+context_compact({
+  target: "vendor-review-method-clear",
+  summary: "Current task: continue the vendor review batch. State: one more vendor review is complete; item-specific reasoning no longer needs to stay raw. Reusable method remains the active baseline. Next step: process the next vendor using the same method.",
+  backupCheckpoint: "vendor-review-item-7-history"
+});
+```
+
+## Warning signs
+
+Use stronger checkpoint/timeline/compact discipline when:
+- each item creates lots of local reasoning
+- you are starting to confuse one item's path with another's
+- the repeated work is stretching across many turns

package/extensions/dm-context/skills/context-management/references/retry-branch-and-pivot.md

@@ -0,0 +1,80 @@
+# Retry, Branch, and Pivot
+
+Use this reference when multiple approaches are being tried and abandoned cleanly, such as:
+- trying A / B / C approaches
+- failed branches that should not pollute the main line
+- compare-and-choose work
+- strategy pivots or goal shifts
+- restarting from a focused working set after a dead end
+
+This is a **cross-cutting pattern reference**. Read it alongside a primary reference such as search/research, development/troubleshooting, or planning/execution when branch behavior becomes central.
+
+## Working pattern
+
+1. Checkpoint before opening a risky branch or alternative path.
+2. Explore or implement that branch.
+3. If anchor choice becomes unclear, inspect timeline.
+4. Once the branch produces a stable lesson, decision, or dead-end, compact to the anchor that removes branch noise while preserving the state needed for the next attempt.
+5. Continue with the next branch or the chosen direction from that focused state.
+
+## When to review timeline
+
+Run `context_timeline` when:
+- multiple branches now exist
+- you are unsure which branch actually stayed useful
+- you need to choose which pre-branch or older anchor gives the next attempt the best working set
+- the next direction is clear but the old branch still clutters active context
+
+## When to compact
+
+Compact when:
+- a branch clearly failed
+- a comparison is complete and one option won
+- the direction changed enough that the old path is now baggage
+- the next attempt should start from a focused state rather than the raw failed branch
+
+When compacting after an abandoned branch, preserve:
+
+- what was tried
+- why it failed or was rejected
+- what should not be repeated
+- what remains valid
+- the chosen next approach
+
+## Strategy pivot
+
+Use this pattern when the old direction no longer makes sense even though the task is still continuing.
+
+Examples:
+- the original approach is no longer viable
+- the user's priority changed
+- the scope narrowed or widened enough that old execution noise is now baggage
+
+In these cases:
+- summarize what still matters
+- compact to the anchor that removes the stale branch while preserving current task state
+- continue under the new direction
+
+## Example rhythm
+
+```javascript
+context_checkpoint({ name: "oauth-fix-start" });
+
+// ... try cookie-based approach ...
+
+context_compact({
+  target: "oauth-fix-start",
+  summary: "Current task: continue the OAuth fix with a new approach. State: cookie-based approach is not viable because the callback flow loses session continuity. Rejected path: do not repeat cookie-based continuity for this flow. Still valid: callback validation and provider config findings. Decision: switch to signed state tokens. Next step: implement the signed-state approach.",
+  backupCheckpoint: "oauth-cookie-approach-history"
+});
+context_checkpoint({ name: "oauth-signed-state-start" });
+```
+
+## Common mistakes
+
+Avoid:
+- opening alternative branches without a clean checkpoint first
+- dragging failed branches forward after their lesson is already clear
+- omitting the rejected path, failure reason, or chosen replacement from the compact summary
+- compacting to a point that still includes the branch you meant to abandon
+- treating every branch as equally worth preserving

package/extensions/dm-context/skills/context-management/references/search-research-and-reading.md

@@ -0,0 +1,103 @@
+# Search, Research, and Reading
+
+Use this reference when the work is mainly driven by large amounts of input material, such as:
+- searching
+- research
+- web search
+- browser-driven information gathering
+- reading many files, logs, docs, webpages, or web results
+- review-heavy reading
+- comparison-heavy reading
+- audit or inspection across many sources
+
+This reference is for **input-heavy work where the process is much larger than the final conclusion**. It is especially relevant for web search and browser/page reading, where the information density is often low and the raw trail becomes stale quickly. If the main anchor is an explicit plan or todo list, use `planning-and-execution.md` instead.
+
+## Working pattern
+
+1. Create a checkpoint before a large search or reading loop.
+2. Search, browse, read, inspect, and follow leads normally.
+3. If you lose orientation, review the timeline.
+4. Once the investigation yields a stable finding and there is another step to take, compact to the anchor that gives the next step a focused working set.
+5. Continue with the conclusion, recommendation, or next action instead of carrying the entire raw exploration forward. If the finding is the final answer to the user's current request, answer first and wait; compact on the next user message if it starts new work.
+
+Do not stop at "I already made a checkpoint" if the investigation phase is complete and the conversation is continuing. The cleanup move for completed research is usually a compact to the anchor that preserves only the raw context the next step still needs.
+
+**Important:** “another step” includes the next phase of the same request. If you searched to find the right data source, previous task record, API shape, rule id, or query pattern, then the next execution step (running the real query/export, implementing, validating, etc.) is an immediate continuation. Compact before that execution step, not only before a future user message.
+
+## When to checkpoint
+
+Checkpoint:
+- before the first big search pass
+- before opening a browser-heavy or webpage-heavy reading pass
+- before diving into a new evidence branch
+- after a stable intermediate conclusion
+- before changing investigation direction
+
+Example checkpoint names:
+- `incident-search-start`
+- `vendor-review-evidence-branch`
+- `api-timeout-investigation-midpoint`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- you have followed several leads
+- you are no longer sure what the main anchor is
+- the investigation has already produced multiple checkpoints
+- you are deciding which path should be compacted
+
+## When to compact
+
+Compact after the investigation produces one of these and there is a continuation that benefits from cleanup:
+- a stable root cause
+- a stable comparison result
+- a dead-end conclusion
+- a shortlist of viable next actions
+- a located data source, old conversation, schema, rule id, query/API pattern, or other fact that unlocks execution
+
+If you already have one of these, the investigation phase is usually complete enough to compact. If the next step is to use the finding in another tool call, compact first. If there is no continuation yet because you are about to give the final answer, wait until the next user message before deciding.
+
+Do not compact in the middle of a still-open search loop just because the thread feels busy.
+
+## Message quality for research compactions
+
+Research compactions are especially sensitive to summary quality. The raw exploration may contain details that become important later, but returning to the backup branch is a context switch. Preserve the state needed to use the finding, not the whole journey.
+
+Include:
+- **Current task/state:** what the research unlocked and how it will be used next
+- **Finding:** what is now known
+- **Source anchors:** key files, URLs, docs, sessions, commands, queries, or records used to reach the finding
+- **Evidence:** important numbers, errors, examples, IDs, or constraints that support the finding
+- **Rejected leads:** only expensive dead ends that future-you should not repeat
+- **Open questions:** what is still uncertain
+- **Next step:** what to do immediately after compact
+- **Backup pointer:** if `backupCheckpoint` is set, when to return to it
+
+Do not compress research to only “found the answer”. That forces future-you to either trust an unsupported conclusion or switch back to the backup for basic details.
+
+## Typical rhythm
+
+```javascript
+context_checkpoint({ name: "timeout-investigation-start" });
+
+// ... search logs, read code, compare docs, inspect outputs ...
+
+// Stable finding found and the next action is execution/validation, so compact before continuing.
+context_timeline();
+
+context_compact({
+  target: "timeout-investigation-start",
+  backupCheckpoint: "timeout-investigation-raw-history",
+  summary: "Current task: plan mitigation for API timeouts. State: DB connection pool exhaustion is the likely root cause. Evidence: logs show pool wait timeouts during peak traffic; config has pool size 10; no network errors found in the checked logs. Rejected lead: API gateway timeout was downstream of DB waits, not the origin. Backup: timeout-investigation-raw-history if exact log lines are needed. Next step: propose mitigation and validation steps."
+});
+```
+
+## Good compact outcomes
+
+After compacting, you should be able to continue with:
+- the finding
+- the recommendation
+- the next verification step
+- the next narrower investigation
+
+You should not still need the whole raw trail in active context unless the investigation is still ongoing.

package/extensions/dm-context/skills/context-management/references/task-switching-and-cleanup.md

@@ -0,0 +1,73 @@
+# Task Switching and Cleanup
+
+Use this reference when the main problem is not the task domain itself, but a change in thread state, such as:
+- the user inserts a temporary side task
+- the user starts a new task after a completed noisy task
+- you need to pause one line of work and resume it later
+- several active fronts now exist
+- the thread is already messy and needs cleanup before continuing
+- a finished noisy phase should be summarized and left behind before new work starts
+
+This reference is for **pause/resume, cleanup, and clean continuation**. It is not for repeated similar items or plan-driven execution.
+
+## Three common variants
+
+### Interruption / task switch
+Use when you are actively switching away from one line of work and intend to come back.
+
+### Completed-task handoff
+Use when a previous task is complete, the user has started a new task or given an explicit next instruction, and the previous task's raw path is noisy enough that it should not be carried into the new work. A request for review, feedback, or an explanation of the completed work is not this handoff.
+
+### Cleanup and continue
+Use when the thread is already stale or messy and you want to compress it now, even though context management is being adopted late.
+
+## Working pattern
+
+1. Inspect timeline if anchor choice is unclear.
+2. Before switching away or compacting a noisy path, preserve or choose the anchor that will give the resumed/new task a clean working set.
+3. If needed, create a backup checkpoint for the current noisy branch.
+4. If the user has just started a new task after a completed noisy task, compact before doing the new task so the completed task becomes a compact summary rather than active baggage.
+5. If the user asks a concrete side question while noisy mainline work is active, pause or summarize the active work, compact if the raw mainline history is no longer needed for the side question, answer the side question, and preserve how to resume the paused work.
+6. Handle the side task or cleanup move.
+7. Compact away the stale path when the handoff summary is clear.
+8. Resume from the paused anchor or continue from the compacted state.
+
+## Useful anchors
+
+Example checkpoint names:
+- `primary-task-paused`
+- `migration-mainline-paused`
+- `release-investigation-paused`
+- `cleanup-pre-noise-anchor`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- multiple interruptions happened
+- the pause lasted many turns
+- several side-task branches now exist
+- you are unsure which anchor gives the resumed/new task the right working set
+- the thread is already messy and you need to find the right pre-noise checkpoint
+
+## When to compact
+
+Compact when:
+- the interruption created lots of noise
+- the side task is done and should not stay active in full
+- the user begins a new task after a completed noisy task and the previous raw path is no longer useful in full
+- a stale path is making current reasoning worse
+- the useful state is now much smaller than the accumulated process
+- you can express the handoff clearly in a summary
+
+Do not compact at the instant you finish a user-visible task if there is no known continuation. In that moment, deliver the answer and wait, retaining the raw trail for review, feedback, or questions about the work. If a later user message starts a new task or establishes an explicit next phase, that is the right time to decide whether compacting the completed task helps before proceeding. If the completed task changed files, browser state, tickets, or remote services, include those side effects in the handoff summary because the context move does not undo them. If the interruption was tiny and clean, a compact may be unnecessary. A checkpoint before switching away is still the key move.
+
+## Common mistakes
+
+Avoid:
+- switching away without a pause checkpoint
+- compacting immediately after a final answer just because the task completed
+- starting a new, unrelated user task while still carrying the previous task's full raw path
+- returning to the main line while still carrying the side task's full raw path
+- trying to clean up without first checking timeline when anchor choice is unclear
+- resetting past still-valid near-term context without carrying it in the summary
+- forgetting that files and external systems remain in their latest state after context navigation

package/extensions/dm-context/src/context.js

@@ -61,7 +61,8 @@ export default function context_default(pi) {
       const toolDefTokensRaw = estimateTokens(JSON.stringify(activeToolDefs));
       const totalActual = usage.tokens;
       const limit = usage.contextWindow;
-      if (totalActual == null || limit == null || usage.percent == null) {
+      const usagePercent = usage.percent;
+      if (totalActual == null || limit == null || usagePercent == null) {
         ctx.ui.notify("Context usage info not available.", "warning");
         return;
       }
@@ -113,7 +114,7 @@ export default function context_default(pi) {
           }
           gridLines.push(rowStr.trimEnd());
         }
-        const totalUsageTitle = `${theme.fg("text", theme.bold("Total Usage".padEnd(16)))} ${theme.fg("text", theme.bold(formatTokens(totalActual).padStart(7)))} ${theme.fg("text", theme.bold(`(${usage.percent.toFixed(1).padStart(5)}%)`))}`;
+        const totalUsageTitle = `${theme.fg("text", theme.bold("Total Usage".padEnd(16)))} ${theme.fg("text", theme.bold(formatTokens(totalActual).padStart(7)))} ${theme.fg("text", theme.bold(`(${usagePercent.toFixed(1).padStart(5)}%)`))}`;
         const catDetailLines = categories.map((cat) => {
           const labelStr = cat.label.padEnd(14);
           const valStr = formatTokens(cat.value).padStart(7);