---
name: provenance-trace
description: Trace published DocMason knowledge objects or answer text back to evidence units and provenance records.
---

# Provenance Trace

Use this skill when the task is to prove where a knowledge object or answer came from.

Use it directly for explicit provenance or citation requests, or let `ask` route here automatically.

Direct public `trace` remains a legal operator provenance surface.
It does not substitute for canonical ask when the user is really asking for ordinary answer completion.

## Required Capabilities

- local file access
- shell or command execution
- ability to inspect structured JSON output

If the agent cannot inspect the local trace artifacts or source evidence, stop and explain that reliable provenance tracing is not possible.

## Procedure

1. Use `current` as the default knowledge-base target unless the task explicitly says otherwise.
2. For citation-first tracing, run:
   - `docmason trace --source-id <source_id> --json --compact`
   - optionally add `--unit-id <unit_id>` for unit-level detail
   - if you genuinely need nested support objects or detailed render metadata, rerun full `--json` to a local file and inspect it selectively instead of pasting the raw payload into chat
   - keep DocMason workspace commands sequential inside the same workspace session; do not overlap `trace`, `retrieve`, `sync`, `status`, or `validate-kb` while a lease-owning command is still active
3. For answer-first tracing, run:
   - `docmason trace --answer-file <path> --json --compact`
   - or `docmason trace --session-id <session_id> --json --compact`
   - do not invent a new freeform `--source-ref` surface in this phase; public trace remains ID-first
4. Inspect:
   - `payload_detail`
   - any inherited `reference_resolution` block on answer-first traces
   - `answer_state`
   - source provenance
   - unit consumers
   - incoming and outgoing relations
   - grounding status for each answer segment
   - compact `supporting_source_ids`
   - compact `supporting_unit_ids`
   - `supporting_artifact_ids`
   - `supporting_overlay_unit_ids`
   - segment `support_lane_counts`
   - segment `artifact_support_count`
   - segment `semantic_support_count`
   - artifact `focus_render_assets` when present
   - render-inspection requirements
   - if the provenance judgment depends on nested `artifact_supports`, `semantic_supports`, overlay consumed inputs, covered slots, blocked slots, render refs, `render_page_span`, `bbox`, `normalized_bbox`, or sidecar paths, inspect a file-first full trace capture instead of the raw chat payload
5. If any segment is only partially grounded or unresolved, say so explicitly and avoid pretending stronger provenance than the trace supports.
6. Return the final provenance or groundedness judgment to the main agent instead of treating trace output as a final user answer by itself.
7. If you need to export a scratch trace note and the user did not specify a destination, place it under `runtime/agent-work/`.

## Escalation Rules

- If `render_inspection_required` is true, inspect the cited render assets before claiming a confident conclusion.
- If the trace cannot resolve the requested source, session, or answer path, surface the not-found failure directly.
- If the traced answer state is not `grounded`, qualify or abstain rather than overclaiming support.
- If answer-first trace inherits an `approximate` or `unresolved` reference-resolution block, preserve that boundary in the provenance summary instead of silently upgrading it.

## Completion Signal

- The workflow is complete when the main agent has a clear provenance summary, including any `answer_state`, unresolved segments, and render-escalation requirements.

## Notes

- Phase 4 tracing reads `knowledge_base/current/trace/` by default.
- Answer-first tracing stores structured local logs under `runtime/logs/`.
- `--session-id` works only for sessions that contain a reusable final answer.
- In Phase 6b2, answer-first trace reuses the same shared reference-resolution contract already attached to the originating ask turn or retrieval session.
- When a trace says render inspection is needed, inspect the render assets before claiming a confident conclusion.
- Ordinary natural questions should usually begin at `ask`, which can route here when provenance is the real intent.