Tracebook

---
name: tracebook
description: MUST invoke before any software-development work in the session. This includes analysis, scaffolding a new project, debugging, review, code changes, tests, builds, deploys, CI/CD, and incidents. It applies to work outside the current repository too. Loads external project knowledge context first. After task completion, evaluates the write gate for durable knowledge capture. Skip only for general Q&A or non-project conversations. Load SKILL.md using Tracebook’s path in the skill catalog.
---

# Tracebook

Use Tracebook as the external, durable knowledge layer for a coding task. Keep
business code and long-lived project analysis separate.

## Quick Start

Copy these commands. `SKILL_DIR` holds this `SKILL.md`; `ROOT` is
`TRACEBOOK_ROOT` when set, else `~/.tracebook`; `CWD` is the target project root
(its Git root when available), not necessarily your shell's cwd.

```bash
# 1. Before any work: read-only check. If it returns blocked:true, run the
#    command in required_action.argv, then continue with step 2.
python "$SKILL_DIR/scripts/tracebook_runner.py" preflight --root "$ROOT" --cwd "$CWD"

# 2. Load task context (lock-free read). Add --evidence-path <file> to find
#    knowledge backed by a specific source file.
python "$SKILL_DIR/scripts/tracebook_runner.py" context-read-path \
  --root "$ROOT" --cwd "$CWD" --profile adaptive --query "<task text>"

# 3. After the task, once per knowledge item that passes the write gate.
#    Wrap UTF-8 as an integrity-checked ASCII envelope; never write a temp file.
{
  python "$SKILL_DIR/scripts/tracebook_request_envelope.py" --request - <<'JSON'
{
  "operation": "create",
  "knowledge_id": "refund-retry-policy",
  "scope": "project",
  "kind": "decision",
  "title": "Refund retry policy",
  "body": "Refunds retry at most twice, 3s timeout each.",
  "evidence": ["src/order/RefundController.java:L87"]
}
JSON
} | python "$SKILL_DIR/scripts/tracebook_runner.py" capture \
  --root "$ROOT" --cwd "$CWD" --request - --today "$(date +%F)"
```

On Windows PowerShell 5.1 or 7, put the same JSON in a here-string and pipe
`New-TracebookRequestEnvelope.ps1 -Json $request` to the Runner. The envelope
is ASCII-only and carries the original UTF-8 SHA-256, so native-command pipe
encoding and console code pages cannot alter it. Legacy raw UTF-8 JSON remains
accepted, but it is unsafe for non-ASCII text through PowerShell 5.1's default
pipeline. A request with high-confidence lossy-text markers is rejected before
project resolution; use `--allow-suspicious-encoding` only for intentional
ASCII question-mark runs or replacement-marker text.

Then verify the write with `check` (see Verify Knowledge Writes). For a complete
capture → immediate user summary → check → conditional audit → final review
sequence, read the [closeout workflow](references/closeout-workflow.md) and use
the packaged [executable example](examples/verify_capture.py) with the retained
capture response. It preserves separate write/check/audit results and never
replays capture. The block above
settles only which command to run; the sections below govern when each step
applies and what may be captured.

## Hard Boundaries

- Use `TRACEBOOK_ROOT` when set; otherwise use `~/.tracebook` as the default external knowledge root.
- Do not modify business repositories to install or operate Tracebook.
- Do not discover, import, copy, or modify an existing external knowledge root automatically.
- Do not create a project-level `AGENTS.md` in a knowledge directory.
- Do not store raw chat transcripts, complete logs, or unverified AI assertions
  as durable knowledge.
- Do not run an MCP service, daemon, cloud service, vector database, or
  API-key-dependent workflow.

## Initialize and Resolve Context

1. Set `SKILL_DIR` to the directory containing this `SKILL.md`. Identify the
   intended target path, not merely the agent's current working directory.
   For an existing project, resolve its Git root when available and read its
   `AGENTS.md` when present. For a new or uncertain target, first run
   `$SKILL_DIR/scripts/tracebook_runner.py preflight --root <external-root>
   --cwd <intended-target>` before creating files. `preflight` is read-only:
   it must not initialize a root or register a project.
2. Set the external root to `TRACEBOOK_ROOT` when configured, otherwise
   `~/.tracebook`. Run `$SKILL_DIR/scripts/tracebook_runner.py preflight --root
   <external-root> --cwd <project-root>` first. For an already registered
   project, load task context with `context-read-path --root <external-root>
   --cwd <project-root> --profile adaptive --query <task text>`. This is the normal lock-free read
   path: it does not initialize, register, repair health, recover transactions,
   or create lock files.
   If `preflight` returns `blocked: true`, execute the command in
   `required_action.argv`, then run `context-read-path` before beginning
   software-development work.
3. Run `$SKILL_DIR/scripts/tracebook_runner.py resolve --root <external-root>
   --cwd <project-root>` only to activate an unregistered project, repair a
   root, seed a legacy project's first snapshot, or before a write/health
   operation that requires maintenance permission. `resolve` may acquire locks
   and modify the external knowledge root; do not present it as a read command.
4. New roots are initialized as schema version 2. A pre-existing root without
   the schema-v2 marker is rejected explicitly: never migrate, infer IDs for,
   or mix legacy knowledge pages with schema-v2 authority pages.
5. The runner creates or repairs only missing external-root template files,
   resolves the project from its registered location and optional normalized
   Git remote, and returns the required `read_paths` plus `knowledge_language`.
6. Do not initialize a project directory beyond `index.md` and
   `project-status.md` until there is durable knowledge to write.
7. If `resolve` refuses transaction recovery, do not edit
   `.tracebook-state` manually. Run
   `$SKILL_DIR/scripts/tracebook_runner.py transactions --root <external-root>`
   first. This diagnostic command is read-only and reports whether each
   transaction is recoverable or blocked. Run `recover-transactions` only for
   an explicit safe roll-forward; it never discards, quarantines, or overwrites
   a changed target.
8. Use the returned `knowledge_language` for future human-readable knowledge
   content. `zh` means write new explanatory prose in Chinese; `en` means
   English. Do not translate or rewrite existing entries merely because the
   root preference changed. Keep paths, Markdown links, lifecycle values,
   evidence references, and structured JSON fields unchanged.

Do not decide that knowledge is irrelevant before the preflight/read phase.
An empty structured result is valid; skipping Tracebook because the target is
new, outside the current repository, or of uncertain relevance is not valid.

## Load Knowledge Before Engineering Work

For nontrivial software-repository work, default to this read phase even when
the user did not explicitly request Tracebook. Read the external root
`AGENTS.md`, global health overview, current project index, project status,
and the current project's `health-status.md` in this order. The global overview
retains every scope's risk, dates and counts; its `Issues` column counts generated
findings and `Details` links to full scope reports. Always read the current
project's full health page, including manual notes. Follow other scope links only
when the task explicitly includes those scopes or requests a global health review.
The overview is persisted state, not a fresh check or a cross-scope atomic snapshot;
its legacy top fields are not global totals. Existing verbose overviews remain
readable and become compact at the next authorized health rebuild, never during
preflight/context reads. Then select only documents relevant to the task.
Repository-local design documents are task input even when they are ignored or
untracked by Git. Discover relevant project documents from the filesystem, not
from `git ls-files` or an ignore-aware file list alone. Use each document's
declared status, baseline, and later superseding decisions to judge authority;
Git tracking is release-review metadata, not a truth or relevance boundary.
For portable `rg` searches, use this sequence:

1. Set the working directory to the search root and use `.` as the path.
2. Pass quoted file patterns with `-g`.
3. When scope matters, list the selected files first:
   `rg --files . -g 'ddl/*.sql' -g 'test_*.py'`.
4. Search the selected files:
   `rg -n -e '<pattern>' . -g 'ddl/*.sql' -g 'test_*.py'`.

If already in `ddl`, use `-g '*.sql'`. This keeps commands portable across
PowerShell, Bash, and Zsh; check stderr and the file list when completeness matters.

Do not load the knowledge root's own complete logs, raw material, archive
directories, or `99-archive` without a tracing, audit, deep-health, or
explicit-user reason. This bounds what is read out of the knowledge base; a log
the user supplies for analysis is task input and is unaffected. After the
minimal read set, call `tracebook_runner.py context-read-path --cwd
<project-root> --profile adaptive --query <task text>` and read only the returned schema-v2
authority pages. It returns the last committed project snapshot without
blocking on a same-project writer. A `PROJECT_ACTIVATION_REQUIRED` response
means the target has not been registered and must be activated with `resolve`
before project context can be read. Context failure must be reported and may
fall back to index navigation; do not pretend a structured search succeeded.
Retrieval matches literal tokens (CJK bigrams, whole English words and identifier
components), with complete identifiers prioritized below explicit Current evidence
paths and exact knowledge IDs. A whole hyphenated query does not expand into its
generic components; use a component explicitly when needed. Identifier matches
do not establish business applicability. There is no stemming or synonym inference,
so prefer words that actually appear in the knowledge —
if a query returns nothing, retry with terms from the project index or an exact
`knowledge_id` rather than a paraphrase.

The adaptive opening profile searches Current first. Only when that query has
zero eligible Current matches does it use History to discover an entity, and it
still returns the selected Current/as-of version without attaching History by
default. Check `adaptive_history_fallback`, `match_source`, and
`matched_version`; adaptive does not infer synonyms, judge relevance, widen
scope, or replace the explicit audit required for historical analysis.

When the task asks about history, versions, changes, Git commits, code
evolution, regression, or why a decision changed, use `--profile audit` before
concluding. It can discover eligible entities through old terms in History,
but returns the selected Current version with `match_source` and `matched_version`.
`--include-history` alone only attaches history to entities already found.
A current-worktree `git
status` or `git diff` check does not require History unless historical context
is requested. Audit is still bounded and local; it does not widen the selected
project or system scope.

An empty, truncated, or merely related result is not enough to establish a
conclusion. Use a concrete new key for bounded follow-up and read the complete
Current body and evidence of decisive entities with `--knowledge-id <id>
--full-content`. This remains a lock-free snapshot read and never silently clips
the body. Check result/omission counts; compare `read_snapshots` and versions when
combining reads. A 500-character `excerpt` is a discovery aid, not a full fact.
Shared domain/pattern pages retain their existing authority-read semantics;
project snapshot provenance does not claim a cross-scope atomic snapshot.
Follow [retrieval timing rules](references/retrieval-timing-rules.md) for when to
broaden the search to History and when to stop.

To find knowledge from a source file — a path in a stack trace or a log the user
supplied — pass `--evidence-path <repo-relative-or-project-absolute path>`,
repeating it per file, with or without `--query`. Entities listing that file as
formal `## Current` evidence are marked `evidence_match: true` and ranked first;
a prose mention or a History reference never earns that mark. It requires exactly
one project at the current snapshot, so `--scope domain/pattern/all` and `--as-of`
are rejected, and at least one of `--query` or `--evidence-path` must be non-empty.

The opening read is not the only retrieval. Query again whenever you judge it
useful, most often once a new file path, identifier, or `knowledge_id` is in
hand, and treat a retrieved conclusion that contradicts a log or the current
source as a finding rather than as truth. Follow
[retrieval timing rules](references/retrieval-timing-rules.md).

## Read Related Projects Deliberately

Start with the active project. For feature work or debugging, also read a related
project when the task depends on its interface, service, or shared contract, or
when a specific information gap requires that project's evidence. The user need
not name it again when task evidence identifies the dependency, its registered
identity is unambiguous, and the read is within the permitted task scope. A local
hit does not establish that the execution context is complete.

Use the members and directed relations returned by `preflight`, plus current
source, configuration, logs, or verified knowledge, to identify the provider.
Use `project-search --root <external-root> --query <name-or-id>` when its stable
ID is unknown. Then use the lock-free `context-read --root <external-root>
--project-id <project-id> --profile adaptive --query <concrete-key>`; repeat
`--project-id` only for the projects needed by this question. Results retain
their source project. Selection is an Agent decision; the engine does not infer
dependencies or widen the query scope.

Use `--profile reference` only when the user asks to reuse an existing
project's architecture for a new project. Before that target is activated, use
`context-read --root <external-root> --project-id <source-project-id>
--profile reference --query <task text>`; it has no `--cwd` and must not
initialize or register the target. It returns architecture, module, and
decision knowledge from explicitly selected source projects and excludes
file-level source maps, incidents, and routine change history. Never infer a
reference source from the current workspace alone.

If the task needs a whole registered system, `context --cwd <project-root>
--system-id <system-id>` includes the cwd project and that system's recorded
members; it is a maintenance-capable command, not the lock-free read path above.
A relation alone is not a reason to read every member. If the provider or allowed
scope remains ambiguous, clarify that specific gap rather than guessing. Follow
[cross-project reading rules](references/cross-project-reading-rules.md) for
selection, and [retrieval timing rules](references/retrieval-timing-rules.md) for
full reads, shared budgets, and stopping. Do not scan all registered projects.

## Register a System Relation When the Link Is Structural

Create the relation yourself, without waiting for the user to ask for it, when
all three hold:

1. both projects are already registered (`preflight` or `project-search`
   confirms this — never register a project just to relate it);
2. the link is a stable delivery dependency, not a passing reference. A task
   that captured durable knowledge into both projects is the strongest signal;
   a `check` report may also raise `system_relation_candidate` when one
   project's evidence points into the other's repository;
3. the direction and the relation kind are unambiguous from the task, because
   the runner does not validate `--kind` — you are asserting the semantics.

If any of the three fails, do nothing: do not create a system, do not ask, and
do not guess a relation. Incidental mentions, one-off debugging, and a
documentation example that merely names another repository are not relations.

```bash
SYS=$(python "$SKILL_DIR/scripts/tracebook_runner.py" system-create \
  --root "$ROOT" --name "<system name>" \
  | python -c "import sys,json;print(json.load(sys.stdin)['system']['system_id'])")

for P in "<project-id-a>" "<project-id-b>"; do
  python "$SKILL_DIR/scripts/tracebook_runner.py" system-bind-project \
    --root "$ROOT" --system-id "$SYS" --project-id "$P"
done

# One call per direction; state both when each side constrains the other.
python "$SKILL_DIR/scripts/tracebook_runner.py" system-relate --root "$ROOT" \
  --system-id "$SYS" --source-project-id "<project-id-a>" \
  --target-project-id "<project-id-b>" --kind designs
python "$SKILL_DIR/scripts/tracebook_runner.py" system-relate --root "$ROOT" \
  --system-id "$SYS" --source-project-id "<project-id-b>" \
  --target-project-id "<project-id-a>" --kind implements
```

Report the system name and both relations in the final task report: this is a
durable structural change to the knowledge base.

Follow [reading rules](references/reading-rules.md) for selection and length
limits. Load these references only when their rule applies:

- [directory rules](references/directory-rules.md)
- [automatic creation rules](references/auto-creation-rules.md)
- [writing rules](references/writing-rules.md)
- [frontmatter rules](references/frontmatter-rules.md)
- [source attribution rules](references/source-attribution-rules.md)
- [index maintenance rules](references/index-maintenance-rules.md)
- [log and status rules](references/log-status-rules.md)
- [knowledge lifecycle rules](references/knowledge-lifecycle-rules.md)
- [synthesis rules](references/synthesis-rules.md)
- [health check rules](references/health-check-rules.md)
- [cross-project reading rules](references/cross-project-reading-rules.md)
- [retrieval timing rules](references/retrieval-timing-rules.md)

## Evaluate the Write Gate After the Task

Every engineering task must evaluate the write gate before the final response.
The final report must state a capture and health result when verified durable
knowledge was written. Routine work with no durable conclusion needs no skip
message; explain a skipped capture only when the user asks, capture fails, or
an important unverified/conflicting conclusion remains.

Treat tests and logs as evidence, not durable knowledge by themselves. A root
cause backed by logs **plus** source, configuration, or reproduction does pass
the gate: a defect investigation that read the code to locate the fault normally
qualifies, and that conclusion is worth keeping. What fails is a conclusion
resting on logs alone, temporary Q&A, unverified inference, or when the user
prohibits a write. Never capture raw logs as the knowledge itself.

Evaluate against the task's final state. If source, tests, configuration, Git
commit or tag, deployment, or release state changes after a capture, re-read the
affected `knowledge_id` and evaluate the write gate again. A release entity is
created or revised only after its final tag target, verification results, and
published state are known. Preserve an earlier verified event in History; do not
rewrite it as though it never occurred.

A revise records a material change to the durable entity: its conclusion,
governed evidence, title, or lifecycle facts. New evidence warrants a revise
when it replaces a moved or obsolete source, resolves a health finding, or
materially changes the support for the conclusion. Formatting-only edits and
incidental investigation notes do not; keep those out of durable knowledge or
capture a genuinely independent fact as its own entity.

A proposed direction that has not been authorized for implementation is never
the current version of the main entity. Record it as its own entity with
`status: pending` and `change-status` it to `deprecated` once it is dropped;
writing it as the main entity's Current costs an extra version the moment it is
overturned.

Evaluate the write gate per atomic knowledge item, never per whole task. A task
that produces several independent facts commits each that is new or
materially changed, useful after the conversation, and has a governed
destination — one `capture` call each. Never let one unverified item block the capture of an
already-verified item. Skip an item only when it cannot be split further and its
core conclusion has no evidence. An explicit no-write request disables capture,
not relevant read-only context loading.

An implemented-but-not-yet-accepted change is durable knowledge: capture the
fact that the code or configuration was changed with `status: current`, and
state its verification status and uncovered scope explicitly. Do not write it as
"risk fully closed". Capture a long-lived, clearly unresolved risk as its own
entity with `status: pending`. Do not withhold the confirmed facts because a
dependency — often third-party — cannot yet be confirmed; record that dependency
as a separate `pending` item instead.

Write only verified, durable knowledge: business rules, terminology, scenarios,
module relationships, architecture changes, code paths, API or database
changes, bug root causes, verification conclusions, important risks, and
reusable cross-project patterns.

Classify the destination before writing. Use project documents for
project-specific facts, `02-domain` for reusable business knowledge, and
`03-patterns` for reusable engineering knowledge. Update indexes and status
summaries. Add source references for critical facts; mark incomplete evidence
as `Pending`. Pipe an explicit, ASCII-safe envelope through stdin as shown in
Quick Start, and consume the response's `changed_paths` and `new_paths`. Never
write a temporary request file. (`--request <path>` stays supported for a
pre-existing file outside both governed trees; a path resolving inside the
knowledge root or the business repository is rejected with `INVALID_REQUEST`.)

Each entity body should make explicit: the conclusion as a concrete fact with no
inference mixed in; the evidence located in source, config, logs, tests, or a
Git diff; the verification status (static / runtime / end-to-end / pending); the
scope of services and entry points the conclusion applies to; and only the open
items directly tied to that entity. Prefer "code changed, SIT acceptance
pending, gateway network isolation unverified" over "security fix fully closed".

The request must declare `operation` and a stable lowercase-hyphenated
`knowledge_id`. Use `create`
only for a missing entity. Use `revise` or `change-status` with
`expected_version` for an existing entity; title, body, evidence, and lifecycle
changes retain the original ID. `event_id` remains content-event idempotence,
not entity identity. The runner renders one Markdown authority page per entity
with a Current section and versioned History. `event_id` is output only: the
runner generates it and echoes it in the capture response and as a
`<!-- tracebook:event:... -->` page marker. Never copy it back into a capture
request — an `event_id` field is rejected as unknown.
Never submit raw transcripts, complete logs, temporary answers, or an
unverified inference as a capture. Use `status: current` with an `evidence`
list for confirmed knowledge. Use `status: pending` for a durable item that is
confirmed to exist but not yet verified or resolved — a known open risk or
awaited acceptance, not an evidence-poor guess; it may have an empty `evidence`
list. Use
`status: deprecated` for information that no longer applies. Use
`status: superseded` only with a `replacement_knowledge_id` for an existing
`current` successor knowledge entity. A replacement pointer is invalid for all
other statuses. The successor is resolved beside the entity
it replaces, so a project entity requires a successor of the same `kind`;
domain and pattern paths carry no kind and accept any. When the successor is a
different project kind it is usually a different fact rather than a new version
— use `deprecated`, which needs no replacement, instead of forcing a pointer.

The same entity event is idempotent. A changed body, evidence, title, or
lifecycle state requires an explicit revise/status operation and preserves the
prior version in History. Do not use a repeated title as an implicit overwrite.

Use a lowercase-hyphenated `kind` to select the governed destination; project
kinds include `architecture`, `api`, `business-rule`, `database`, `module`,
`source-map`, `terminology`, `decision`, `incident`, and `change`. `domain`
and `pattern` scopes also use a stable kind. Retired request fields such as
`category`, `topic`, and `replacement` are rejected; use `kind` and
`replacement_knowledge_id` as the schema-v2 contract defines.
Project entity paths are derived from scope, kind, and `knowledge_id`; domain
and pattern paths use scope plus `knowledge_id`, while `kind` remains governed
metadata. Do not create aggregate pages or use a topic split to route schema-v2 knowledge. Apply
frontmatter and lifecycle labels when required.
## Verify Knowledge Writes

Use [closeout workflow](references/closeout-workflow.md) when executing this
phase, especially across Windows host/shell boundaries or after partial
failure. A skipped capture is no new write, not proof of a new health check.
If verification fails after capture, report the committed write separately
from incomplete health verification; do not retry capture to fix a check.

After every successful capture, require `changed_paths`, `new_paths`, and
`health_scope` in its structured JSON. Stop and report an incomplete runner
response if `health_scope` is absent or is not `project`, `domain`, or
`pattern`; do not fall back to the default project scope.
Capture `warnings` are non-fatal cleanup diagnostics emitted after the durable
transaction, such as a best-effort snapshot-prune failure. Report them and
continue with the required health check; do not describe the capture as failed.

When a non-skipped capture with changed paths returns `user_summary`, display
it to the user verbatim in the next user-facing message. Do not defer it to
the Final Task Report, paraphrase it, or omit it: this confirms a file write
that has already occurred on the user's system.

Then run `check`, repeating `--changed` for every capture `changed_paths` item
and `--new-path` for every `new_paths` item, and consume its structured JSON:

```bash
python "$SKILL_DIR/scripts/tracebook_runner.py" check --root "$ROOT" --cwd "$CWD" \
  --source-root "$CWD" --today "$(date +%F)" --scope "<health_scope>" \
  --changed "<changed_paths item>" --new-path "<new_paths item>"
```

Use `findings` for deterministic automation and `report` for the human-readable
Markdown view. They describe the same check or audit result; neither authorizes
automatic edits to authority pages.

With `--source-root`, the report's `Review Candidates` section flags Current
knowledge whose evidence files are missing (`source_missing`, strong), changed
after the knowledge was last updated (`source_mtime_newer`, advisory), or
resolve outside the source root (`source_outside_root`, strong). Add
`--review-after-days N` (N > 0) to also flag knowledge not updated in N days
(`review_age_exceeded`, advisory). These are review prompts, not proof a fact is
wrong — verify against evidence before changing any status.

When `check_type: Deep` is returned, do not treat it as a completed Deep check.
Run `$SKILL_DIR/scripts/tracebook_runner.py audit` with the same `--root`,
`--cwd`, `--today`, and `--source-root` values, plus the same scope supplied to
check as `--scope`. Its fact, source, root-cause, and status candidates require
human review before they become durable conclusions. Do not let either command
modify business code.

## Final Task Report

State business-code changes, external-knowledge changes, health-check result,
new durable knowledge, and unconfirmed assumptions.