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:

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.