deep-trace（深迹）

Deep Trace — Line-by-Line Execution Path Tracer

<essential_principles>

Core Concept

Trace code like a debugger stepping through line-by-line, but enriched with:

• Screen: What the user sees when this code runs
• URL: The page/API route where this executes
• Data flow: What data enters, transforms, and exits
• Trigger: What event/action causes this line to execute

Trace Table Format

Every trace outputs a structured table:

## Trace: [description]

| # | File:Line | Code | Screen/URL | Data Flow | Trigger |
|---|-----------|------|------------|-----------|---------|
| 1 | page.tsx:15 | `const router = useRouter()` | /drawings | — | Page mount |
| 2 | page.tsx:16 | `const { id } = router.query` | /drawings?id=123 | id: string | URL params |
| 3 | hook.ts:8 | `const { data } = useQuery(...)` | /drawings?id=123 | id → API call | React render |
| ... | ... | ... | ... | ... | ... |

Principles

1. Diff-first: Start from changed lines, trace outward to entry point and downstream effects
2. Line granularity: Every meaningful line gets its own row (skip blank lines, imports, type-only lines)
3. Screen mapping: Always identify which screen/URL the user is on when this code runs
4. Bidirectional: Trace both UP (who calls this?) and DOWN (what does this call?)
5. Application boundary: Summarize library calls in 1 row, don't trace into node_modules
6. No abbreviation in File:Line: NEVER truncate or ellipsis file names. Always show the full file name (e.g., useSetFormValuesFromQueryStrings.tsx:77, NOT useSetFormValues...:77). Code column may be abbreviated if >80 chars, but file names must be exact.

</essential_principles>

Workflow

Step 1: Identify Target

Determine input source from user's argument:

Step 2: Extract Changed Code

For PR/diff inputs:

1. Parse diff to get changed files and line ranges
2. Group changes by file
3. Prioritize: components > hooks > utils > types

For file/function inputs:

1. Read the target code
2. Identify exported functions/components

Step 3: Find Entry Points

For each changed code section, trace UP to find the entry point:

Changed line → containing function → caller → ... → page component / API route / event handler

Use Serena tools:

• find_symbol — locate the function
• find_referencing_symbols — find callers
• Repeat until reaching a page/route/event boundary

Entry point types:

Step 4: Build Trace Table

Starting from entry point, step through line-by-line:

1. Read the entry point file (Serena find_symbol with include_body=True)
2. For each meaningful line, create a table row:

- #: Sequential step number - File:Line: Full file name + line number. NEVER abbreviate or ellipsis file names - Code: The actual code (backtick-wrapped, may abbreviate if >80 chars) - Screen/URL: What screen/page/URL is active - Data Flow: What data is being read/written/transformed - Trigger: What causes this line to execute (mount, click, API response, etc.)

1. When hitting a function call:

- If it's application code → trace INTO it (sub-steps like 3.1, 3.2,...) - If it's a library call → summarize in 1 row with [lib] prefix

1. When hitting a conditional: note both paths, trace the primary path

Step 5: Annotate with Context

Add these sections after the trace table:

## Summary
- **When**: [user action / event that triggers this code]
- **Where**: [screen URL and component location]
- **What**: [1-2 sentence description of what the code accomplishes]
- **Data**: [key data entities involved, their sources and destinations]

## Key Observations
- [Notable patterns, potential issues, or design decisions]

Step 6: Generate Extension-Compatible Output

After the Summary, generate a separate copyable table for the deep-trace-extension VS Code extension.

Extension format (4 columns, specific header names required):

## 📋 Deep Trace Extension

| file | line | col | reason |
| --- | --- | --- | --- |
| src/components/FreewordSearchFilter.tsx | 40 | 1 | useFreewordSearchFormContext — Component render |
| src/components/FreewordSearchFilter.tsx | 54 | 1 | useWatch target values — Form state change |

Conversion rules from trace table → extension table:

Requirements:

• Every row from the trace table gets a corresponding row
• file must be the full relative path (not just filename). Resolve from project root using Serena if the trace table only has the filename
• Output inside a fenced code block (``` `markdown... ` ```) so users can copy the raw Markdown

Step 6.5: Copy Extension Table to Clipboard (Optional, OS-aware)

Right after printing the fenced extension-table block from Step 6, also pipe that same block into the bundled helper so users can paste straight into the deep-trace-extension without manual selection:

cat <<'EOF' | bash skills/deep-trace/scripts/copy-to-clipboard.sh
| file | line | col | reason |
| --- | --- | --- | --- |
| src/components/FreewordSearchFilter.tsx | 40 | 1 | useFreewordSearchFormContext — Component render |
| src/components/FreewordSearchFilter.tsx | 54 | 1 | useWatch target values — Form state change |
EOF

The helper auto-detects the host clipboard tool:

Behavior contract (do not violate):

• The fenced markdown block from Step 6 is always printed first — clipboard copy is purely additive, never a replacement.
• The script always exits 0, even when no clipboard tool exists. Skill workflow must not fail because clipboard is unavailable.
• The script reports the chosen tool (or skip reason) on stderr, e.g. copy-to-clipboard: copied via pbcopy (macOS). Surface that line back to the user so they know whether to copy manually.

When to skip this step entirely:

• Headless CI / non-interactive runs (no human to paste)
• Sandboxed or remote environments where clipboard access is denied or meaningless
• User explicitly opts out (e.g. security-sensitive context)

Step 7: Save to Memory (Optional)

If the user wants to remember this trace:

Serena write_memory("trace_<descriptive_name>", traceContent)

Examples

Example: Tracing a PR diff

/deep-trace #3548

Output:

## Trace: PR #3548 — フリーワード検索の種別フィルター追加

### Entry: FreewordSearchFilter.tsx (絞り込みPopover内)

| # | File:Line | Code | Screen/URL | Data Flow | Trigger |
|---|-----------|------|------------|-----------|---------|
| 1 | FreewordSearchFilter.tsx:40 | `const { control } = useFreewordSearchFormContext()` | /freeword_search?query=テスト | form context | Component render |
| 2 | FreewordSearchFilter.tsx:54 | `const targetValues = useWatch({ control, name: 'target' })` | same | target: SelectOption[] | Form state change |
| 3 | FreewordSearchFilter.tsx:65 | `useDocumentTypeSettingsQuery(...)` | same | API → document_type_settings | React Query cache/fetch |
| 4 | FreewordSearchFilter.tsx:70 | `const targetOptions = useMemo(...)` | same | settings → SelectOption[] | Deps change |
| 5 | FreewordSearchFilter.tsx:119 | `<MultiSelectRHF ... options={targetOptions}>` | same (Popover open) | targetOptions → UI | User opens filter |

### Summary
- **When**: User opens 絞り込み popover on freeword search page
- **Where**: /freeword_search (ファイルフリーワード検索モード)
- **What**: Shows multi-select filter for 種別 (drawing + document types)
- **Data**: document_type_settings API → SelectOption[] → form state → API search params

## 📋 Deep Trace Extension

Tools Used

Success Criteria

• [ ] Entry point correctly identified (page/route/event)
• [ ] Every meaningful changed line has a trace row
• [ ] Screen/URL column populated for all rows
• [ ] Data flow shows inputs → transformations → outputs
• [ ] Trace is readable top-to-bottom as an execution story
• [ ] Summary captures when/where/what/data
• [ ] Extension-compatible table included with file, line, col, reason columns
• [ ] Extension table uses full relative paths (not just filenames)
• [ ] Extension table wrapped in fenced code block for easy copy
• [ ] Extension table also piped through scripts/copy-to-clipboard.sh (or step explicitly skipped with reason); helper's stderr status surfaced to the user