# Exploration Trace

> Record and visualize the actual project exploration performed while answering a user's question, including searches, files read, line ranges, reasons, findings, and file relationships. Use when the user explicitly invokes $exploration-trace or asks to see the search/read order, exploration log, file-level evidence, or Mermaid graph. This skill observes the task; it does not choose or expand the investigation scope.

- Skill: `aqwsde321/exploration-trace` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aqwsde321/exploration-trace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aqwsde321/exploration-trace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: aqwsde321 (https://skillmd.com/u/aqwsde321)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/aqwsde321/exploration-trace

---


# Exploration Trace

Attach a factual exploration record to the user's original task. Observe the investigation without changing its scope, strategy, or completion condition.

## Core contract

- Solve the user's original question using the normal project workflow.
- Record the searches and file reads that actually occur while solving it.
- Do not perform extra searches, reads, tests, or audits only to make the trace look complete.
- Do not replace the original answer with a trace-only investigation.
- At the end, show the conclusion, chronological trace, evidence map, and Mermaid graph.

The skill is a recording layer, not an exploration-depth selector.

## Record during exploration

Create a logical ledger before the first search and append to it immediately after each meaningful result. Do not reconstruct the sequence from memory after the task is finished.

- `SEARCH`: Record the query, scope, and important candidate paths. A search hit is not a file read.
- `READ`: Record the path, exact line range or `whole file`, reason for reading, and concise findings.
- `FOLLOW`: Record why an import, call, reference, test, or instruction led to the next file.
- `SKIP`: Record an important candidate that was not opened when that omission affects confidence.
- `ERROR`: Record a failed search or read and the fallback used when material.
- `CONCLUDE`: Link each material conclusion to the supporting `READ` entries.

Use actual observed ranges. If line numbers are unavailable, write `line range unavailable`; never guess.

```text
[READ 02] src/order/OrderService.ts:20-95
Reason: confirm the order creation entry point
Finding: calls PaymentService.create()
Next: inspect payment failure handling
```

Group consecutive commands only when they represent one logical action. Do not omit a meaningful branch merely to reduce the count.

## Exploration rules

- Preserve the original question, scope, and normal success condition.
- Use the repository's applicable instructions as the normal workflow requires. Record those reads if they occur.
- Follow the same evidence threshold that would apply without this skill.
- Do not read every file returned by a broad search unless the original question requires a full inventory.
- Do not run tests, runtime checks, dependency audits, or full-repository analysis unless the original task requires them or the user separately requests them.
- If no file was searched or read, say so explicitly. Do not fabricate a trace.
- If an operation fails, record the error and continue only if the original task has a safe fallback.

## Final output

Present information in this order:

1. Conclusion for the original question.
2. Chronological exploration trace.
3. Evidence map linking claims to files and line ranges.
4. Mermaid graph of the actual path from question through searches, reads, follows, and conclusion.
5. Unknowns, failed checks, or incomplete trace limitations.

Always include a Mermaid graph when this skill is active. Keep it small enough to reflect the actual exploration, not a speculative architecture diagram. Use quoted labels and unique node IDs.

```mermaid
flowchart TD
  Q["User question"] --> S1["SEARCH: OrderService"]
  S1 --> R1["READ: OrderService.ts:20-95"]
  R1 --> F1["FOLLOW: PaymentService call"]
  F1 --> R2["READ: PaymentService.ts:10-70"]
  R2 --> C["Conclusion"]
```

If the user asks to see progress while working, emit concise ledger entries after meaningful operations. Otherwise, keep the ledger until the final response and do not narrate every low-level command.

If the user asks to save the trace, create `docs/exploration/<topic>-YYYY-MM-DD.md` before exploration, append the actual logical entries as work proceeds, then finalize the same file with the conclusion and graph. Avoid overwriting an existing report and report the path. Saving changes output destination only; it must not change the investigation.

## Integrity and safety

- Report observable actions and evidence, not private chain-of-thought.
- Never claim a file was read when it was only found by search.
- Never invent a line range, relationship, finding, or command result.
- State when the trace is incomplete or a check could not be run.
- Never include credentials, tokens, private keys, or other secrets. Redact them and record only that sensitive content was omitted.
- Keep implementation changes and exploration-report changes separate in the final summary.