Code Trace
Use the smallest mode that answers the question. The default stance is
evidence-first and read-only: inspect the repository, trace the relevant
boundary, and report what remains unknown. A diagnosis may recommend a repair
or a regression test, but it does not implement the repair.
Modes
| Mode |
Use when |
Completion criterion |
explore |
You need to understand an unfamiliar symbol, file, module, or flow. |
Entry point, caller/callee path, evidence, assumptions, and gaps are recorded. |
diagnose |
A failure, regression, performance problem, data inconsistency, or timing issue needs a confirmed cause. |
One falsifiable root cause is supported by evidence, or the current blocker and next check are explicit. |
history |
You need to know when, why, or by whom behavior changed. |
Blame, timeline, original/problematic comparison, and actionable conclusion are reported. |
select-tool |
You need one code-navigation tool and a fallback chosen. |
One intent row, executable primary call, and concrete fallback or none are returned. |
If --mode is omitted, infer one mode only when intent is unambiguous. A
request to edit a symbol first requires the repository's impact-analysis rule
before any implementation lane touches it; this skill only reports the impact.
When NOT to Use
- Implement a confirmed change → use
flow-drive.
- Review a proposed change → use
change-verdict.
- Review an existing skill document or change → use
change-verdict in its docs or risk mode. Specialized skill governance scoring and stocktake are retired.
explore
- Identify the repository root, question, entry point, and target symbol.
- Follow the repository's CX priority: use
cx overview, then cx definition, then cx references for symbol-level questions. Use the
selected semantic fallback only when CX cannot answer.
- Trace callers, callees, data/control transitions, and observable output
until the relevant boundary is accounted for.
- For
--dual, dispatch an isolated read-only perspective with only the
original question, repository path, and depth. Reconcile evidence after
the primary trace; never seed the second perspective with a conclusion.
- For
--explain --depth brief|normal|deep, keep the response within the
requested depth. Load references/explore/ only for the selected branch.
diagnose
Use the five-phase loop:
Clarify → Gather evidence → Trace and confirm → Design the fix → Preserve knowledge
Before broad theorizing, run the smallest symptom-specific reproduction or
probe that is available and safe. Record the command or interaction, relevant
output, and the expected-versus-actual assertion. If reproduction is
unavailable, blocked, or flaky, state that; for flaky behavior, include the
observed attempts, successes, and known conditions. For performance symptoms,
record a baseline from a comparable workload when available. Reduce one input
at a time only while the check is bounded and preserves the signal. When
changed code, an injected fault, or an altered fixture is what forced that
check red, the red result counts as reproduction evidence only after the
forced-mutation check passes. Confirm a mutation that is already present.
Applying a mutation, or repairing a setup, belongs to the authorized isolated
workflow in references/diagnose/root-cause-tracing.md. See
references/diagnose/reproduction-evidence.md for these evidence details,
including the clean-copy git diff, and
references/diagnose/root-cause-tracing.md when following a call or data path.
Keep diagnosis read-only: do not reproduce a destructive action or write to a
shared database by default. Use existing evidence and authorized read-only
queries; route any side-effecting confirmation through an authorized isolated
environment. Maintain ranked, falsifiable hypotheses with a discriminating
check and evidence that could reject each one. Redact secrets from commands,
logs, traces, and handoffs. Do not promote a plausible explanation to root
cause without a confirming check.
Load the phase-specific material from references/diagnose/ only when that
phase requires it. Inspect a selected bundled script's operation and effects
before running it, keep output bounded, and preserve its actual exit status.
Bundled diagnose scripts are not pre-approved; an unlisted shell command uses
the host's normal permission flow.
Return the phase report in the response and name the single next handoff by
default. Write an investigation artifact only when explicitly authorized; this
skill does not create directories or files and does not implement the proposed
repair.
history
Use the narrowest history query that answers the question: git blame for
ownership, git log --follow for timeline, git log -S/-G for introduction,
and git show/git diff for original-versus-problematic comparison. Pin the
relevant commit range, distinguish author from committer where material, and
avoid changing refs, the index, or the worktree. Load
references/history/commands.md for command/report details and
references/history/wsl-traps.md only when the environment matches.
select-tool
- Read
references/select-tool/decision-tree.md for the local decision table
and tie-breakers.
- Map the request to exactly one intent row and select its primary tool.
- Use the named fallback only when the primary is unavailable or returns no
useful result. Prefer CX when both CX and GitNexus are valid, except for
GitNexus-only operations; leave GitNexus-specific semantics to its external
package skill.
- For a planned edit, rename, or refactor, use the local reference's impact
timing before touching an existing symbol.
Return:
Intent: <matched decision-tree row>
Primary: <exact command or MCP call>
Fallback: <exact command or MCP call, or none>
Output
## Code trace: <mode>
- Target/question: <target>
- Mode/depth: <mode and depth>
- Entry point or fixed commit: <evidence anchor>
- Flow or timeline: <ordered path>
### Evidence
- <file:line, commit, command, or tool result>
### Findings and gaps
- <conclusion, hypothesis state, or unresolved link>
### Next action
- <one handoff, or none>
For diagnose, include expected/actual behavior, reproduction status, the
clean-copy diff verdict when a forced mutation produced the red result, ranked
hypotheses, one confirmed cause or blocker, options/risks/verification intent,
and stop-loss state. The verdict words are defined in
references/diagnose/reproduction-evidence.md. For explore --dual, keep primary and independent
findings separate before the agreement/difference table.
References
references/explore/ — search patterns, explanation depth, and independent perspective.
references/diagnose/ — reproduction evidence, phase templates, tracing, waiting, defense-in-depth, checklists, and scripts.
references/history/ — git command/report reference and environment traps.
references/select-tool/decision-tree.md — edge cases and routing rationale.
Verification
1---2name: code-trace3description: 'Trace unfamiliar code, diagnose a reproducible failure, investigate history, or pick a code-navigation tool, following symbols, callers, data flow, or regressions. Not for implementing a fix, reviewing a diff, or plain-text search. Output: an evidence-backed trace or root cause.'4allowed-tools: 'Read, Grep, Glob, Bash(git log:*), Bash(git show:*), Bash(git diff:*), Bash(git blame:*), Bash(cx:*), Agent'5metadata:6 source: https://skillmd.com/skills/hmj1026/code-trace7 dhpk-capability-id: dhpk.skill.code-trace8 dhpk-name-style: portable-family9 dhpk-invocation-class: implicit-eligible10 dhpk-next:11 PASS: none12 FAIL: none13 BLOCKED: none14 NOT_RUN: none15 UNAVAILABLE: none16---1718# Code Trace1920Use the smallest mode that answers the question. The default stance is21evidence-first and read-only: inspect the repository, trace the relevant22boundary, and report what remains unknown. A diagnosis may recommend a repair23or a regression test, but it does not implement the repair.2425## Modes2627| Mode | Use when | Completion criterion |28|---|---|---|29| `explore` | You need to understand an unfamiliar symbol, file, module, or flow. | Entry point, caller/callee path, evidence, assumptions, and gaps are recorded. |30| `diagnose` | A failure, regression, performance problem, data inconsistency, or timing issue needs a confirmed cause. | One falsifiable root cause is supported by evidence, or the current blocker and next check are explicit. |31| `history` | You need to know when, why, or by whom behavior changed. | Blame, timeline, original/problematic comparison, and actionable conclusion are reported. |32| `select-tool` | You need one code-navigation tool and a fallback chosen. | One intent row, executable primary call, and concrete fallback or `none` are returned. |3334If `--mode` is omitted, infer one mode only when intent is unambiguous. A35request to edit a symbol first requires the repository's impact-analysis rule36before any implementation lane touches it; this skill only reports the impact.3738## When NOT to Use3940- Implement a confirmed change → use `flow-drive`.41- Review a proposed change → use `change-verdict`.42- Review an existing skill document or change → use `change-verdict` in its `docs` or `risk` mode. Specialized skill governance scoring and stocktake are retired.4344## `explore`45461. Identify the repository root, question, entry point, and target symbol.472. Follow the repository's CX priority: use `cx overview`, then `cx48 definition`, then `cx references` for symbol-level questions. Use the49 selected semantic fallback only when CX cannot answer.503. Trace callers, callees, data/control transitions, and observable output51 until the relevant boundary is accounted for.524. For `--dual`, dispatch an isolated read-only perspective with only the53 original question, repository path, and depth. Reconcile evidence after54 the primary trace; never seed the second perspective with a conclusion.555. For `--explain --depth brief|normal|deep`, keep the response within the56 requested depth. Load `references/explore/` only for the selected branch.5758## `diagnose`5960Use the five-phase loop:6162`Clarify → Gather evidence → Trace and confirm → Design the fix → Preserve knowledge`6364Before broad theorizing, run the smallest symptom-specific reproduction or65probe that is available and safe. Record the command or interaction, relevant66output, and the expected-versus-actual assertion. If reproduction is67unavailable, blocked, or flaky, state that; for flaky behavior, include the68observed attempts, successes, and known conditions. For performance symptoms,69record a baseline from a comparable workload when available. Reduce one input70at a time only while the check is bounded and preserves the signal. When71changed code, an injected fault, or an altered fixture is what forced that72check red, the red result counts as reproduction evidence only after the73forced-mutation check passes. Confirm a mutation that is already present.74Applying a mutation, or repairing a setup, belongs to the authorized isolated75workflow in `references/diagnose/root-cause-tracing.md`. See76`references/diagnose/reproduction-evidence.md` for these evidence details,77including the clean-copy `git diff`, and78`references/diagnose/root-cause-tracing.md` when following a call or data path.7980Keep diagnosis read-only: do not reproduce a destructive action or write to a81shared database by default. Use existing evidence and authorized read-only82queries; route any side-effecting confirmation through an authorized isolated83environment. Maintain ranked, falsifiable hypotheses with a discriminating84check and evidence that could reject each one. Redact secrets from commands,85logs, traces, and handoffs. Do not promote a plausible explanation to root86cause without a confirming check.8788Load the phase-specific material from `references/diagnose/` only when that89phase requires it. Inspect a selected bundled script's operation and effects90before running it, keep output bounded, and preserve its actual exit status.91Bundled diagnose scripts are not pre-approved; an unlisted shell command uses92the host's normal permission flow.93Return the phase report in the response and name the single next handoff by94default. Write an investigation artifact only when explicitly authorized; this95skill does not create directories or files and does not implement the proposed96repair.9798## `history`99100Use the narrowest history query that answers the question: `git blame` for101ownership, `git log --follow` for timeline, `git log -S`/`-G` for introduction,102and `git show`/`git diff` for original-versus-problematic comparison. Pin the103relevant commit range, distinguish author from committer where material, and104avoid changing refs, the index, or the worktree. Load105`references/history/commands.md` for command/report details and106`references/history/wsl-traps.md` only when the environment matches.107108## `select-tool`1091101. Read `references/select-tool/decision-tree.md` for the local decision table111 and tie-breakers.1122. Map the request to exactly one intent row and select its primary tool.1133. Use the named fallback only when the primary is unavailable or returns no114 useful result. Prefer CX when both CX and GitNexus are valid, except for115 GitNexus-only operations; leave GitNexus-specific semantics to its external116 package skill.1174. For a planned edit, rename, or refactor, use the local reference's impact118 timing before touching an existing symbol.119120Return:121122```text123Intent: <matched decision-tree row>124Primary: <exact command or MCP call>125Fallback: <exact command or MCP call, or none>126```127128## Output129130```markdown131## Code trace: <mode>132- Target/question: <target>133- Mode/depth: <mode and depth>134- Entry point or fixed commit: <evidence anchor>135- Flow or timeline: <ordered path>136137### Evidence138- <file:line, commit, command, or tool result>139140### Findings and gaps141- <conclusion, hypothesis state, or unresolved link>142143### Next action144- <one handoff, or none>145```146147For `diagnose`, include expected/actual behavior, reproduction status, the148clean-copy diff verdict when a forced mutation produced the red result, ranked149hypotheses, one confirmed cause or blocker, options/risks/verification intent,150and stop-loss state. The verdict words are defined in151`references/diagnose/reproduction-evidence.md`. For `explore --dual`, keep primary and independent152findings separate before the agreement/difference table.153154## References155156- `references/explore/` — search patterns, explanation depth, and independent perspective.157- `references/diagnose/` — reproduction evidence, phase templates, tracing, waiting, defense-in-depth, checklists, and scripts.158- `references/history/` — git command/report reference and environment traps.159- `references/select-tool/decision-tree.md` — edge cases and routing rationale.160161## Verification162163- [ ] Exactly one mode and requested depth are stated.164- [ ] Definitions/references were inspected at symbol or commit granularity before broad search.165- [ ] Every material conclusion has evidence; hypotheses and gaps remain labeled.166- [ ] Dual perspectives, if used, were independent and separately reported.167- [ ] No implementation, fix, refactor, commit, or destructive cleanup was performed.