Taku Compact - Context-Control Habit#

Use /taku-compact to compress active work into a recoverable brief. It is a bonus utility skill, not a seventh Taku phase.

Rule labels: [IRON LAW] means a non-negotiable correctness constraint. [GUIDANCE] means a strong default that may adapt when context justifies it.

Compact preserves current task state. Reflect preserves long-term learnings. Never write .taku/learnings from this skill. You may list reflect_candidates, but /taku-reflect is the only path that can promote them after user approval. A reflect_candidates entry is not a recorded learning and must never be worded as one.

Host Boundary#

This skill does not control the host transcript, context window, message slicing, archive behavior, or clear behavior. It creates a handoff brief from available evidence. Do not claim that tool calls, tool results, or transcript events were compacted.

If a future host exposes transcript ranges, record them as retrieval hints only after verifying they are available. Otherwise use file, diff, command, log, prior-brief, and current-session anchors.

Mode Selection#

Accept an explicit mode when the user provides one:

ModeUse WhenPreserve FirstresumeThe same agent or user will continue laternext step, open todos, blockers, recent decisionshandoffAnother agent or session needs to continuebackground, scope, decisions, files, verification, next stepdebugInvestigation or failed checks are in progresssymptoms, reproduction, evidence, failed hypotheses, next probereviewA dirty diff or delivery review is nextdiff intent, risk areas, test coverage, scope drift, blockersdesignThink/Plan/product discussion needs preservingconstraints, tradeoffs, confirmed decisions, open questionsresearchSource reading or technical exploration needs preservingsources, findings, confidence, unresolved questions, followups

If no mode is provided, infer it from the request and current state. Record mode_selection_reason in the brief. Prefer handoff when multiple modes fit and the user asked for general compacting.

State Scan Contract#

[IRON LAW] Run an evidence-first state scan before writing the brief. Do not summarize from memory first.

1. Durable Sources#

Read or inspect these when present:

• DESIGN.md
• PLAN.md
• README.md
• AGENTS.md
• CLAUDE.md
• .taku/context/current.md
• .taku/context/compact-*.md
• .taku/learnings/*.jsonl as approved context only

Only include stable-layer details that affect the active task. If a durable source is missing or irrelevant, record that in source_coverage; do not treat it as a blocker.

2. Repo Evidence#

Inspect git and file-system evidence when a repo is available:

• git status --short
• git diff --stat
• git diff --name-only
• relevant git diff hunks for changed files
• git log -n 3 --oneline

Changed files must come from git or the file system, not guesswork. A clean diff means no durable code changes were observed; it does not mean no progress occurred.

3. Session-Visible State#

Treat visible conversation and tool outputs as first-class state:

• recent user decisions and corrections
• explicit constraints and preferences
• command results visible in this session
• tool output, agent findings, review findings, and debug observations
• design/research progress that has not been written to project files

Mark conversation-derived claims as user and command/tool-output claims as tool. Do not present them as file-backed project truth unless they were written to a durable artifact.

4. Source Tags and Confidence#

Every important claim must carry one of these source categories:

• file: project file, Taku context file, approved learning, or file-system inspection
• git: status, diff, or commit history
• tool: command output or tool result visible in the session
• user: explicit user statement, correction, or approval
• inferred: agent synthesis from other evidence
• unknown: unavailable or unverified evidence

Do not say tests passed unless actual command output or explicit user-provided evidence shows that.

Include state_confidence for goal, changed files, verification, and next step using high, medium, low, or unknown.

Brief Output#

Use references/compact-brief.md as the local brief scaffold. Fill every applicable field. Remove irrelevant mode-specific sections, but keep unknowns, retrieval_hints, and completeness_check.

Default persistence:

1. Create .taku/context/ if needed.
2. Write the latest brief to .taku/context/current.md.
3. Write the same brief to .taku/context/compact-YYYYMMDD-HHMMSS.md.

If files cannot or should not be written in the current host, output the brief in chat and mark persistence: chat_only.

Mode-Specific Requirements#

Resume#

Include:

• the first concrete next action
• unresolved blockers
• open todos
• recent session context needed to avoid rework

Handoff#

Include:

• background and current scope
• decisions and user constraints
• changed files or confirmation that none were observed
• verification state
• exact restart instructions for the next agent

Debug#

Include:

• observed symptoms
• reproduction steps
• evidence collected
• failed hypotheses and why they failed
• next probe

Never describe a fix as verified without evidence.

Review#

Include:

• diff intent
• changed files
• risk areas
• test coverage observed
• scope drift check against PLAN.md or user intent when available
• pre-ship blockers

Design#

Include:

• user constraints
• options considered
• tradeoffs
• confirmed decisions
• open questions
• recommended next planning step

Research#

Include:

• sources inspected
• key findings
• confidence by finding
• unresolved questions
• follow-up searches or files to inspect

Completeness Check#

Before finishing, verify the brief includes:

• user constraints or unknown
• open todos or none_observed
• failed attempts or none_observed
• verification state with evidence or not_established
• changed files with sources or none_observed
• retrieval hints
• unknowns
• mode-specific required fields
• source tags for important claims

If a required item is missing, fix the brief before presenting it.

Non-Goals#

• Do not edit implementation files.
• Do not update PLAN.md status.
• Do not run formatters or codegen.
• Do not commit, push, or open a PR.
• Do not fix bugs.
• Do not write .taku/learnings.
• Do not add archive or clear semantics.