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:

Input	Detection	Action
PR number	#1234 or number	gh pr diff <number>
Branch diff	--diff or no arg	git diff HEAD~1 or git diff dev...HEAD
File path	.ts, .tsx, etc.	Read file, trace from exports
Function name	text without path	Serena find_symbol

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:

Type	Example	Screen/URL
Page component	pages/drawings/index.tsx	/drawings
API route	pages/api/drawings.ts	POST /api/drawings
Event handler	onClick, onSubmit	Button click on current page
Effect	useEffectOnMount	Page load
Provider	_app.tsx wrapper	All pages

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.)

3. 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

4. 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:

Trace column	→ Extension column	Rule
File:Line	file + line	Split on last : — file path before, line number after
—	col	Always 1 (column info not tracked in trace)
Code + Trigger	reason	Combine: short code description + — + trigger

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:

OS / environment	Tool tried
macOS	pbcopy
Linux (Wayland session)	wl-copy
Linux (X11 session)	xclip -selection clipboard → xsel
WSL	clip.exe
Cygwin / MinGW / MSYS	clip
No tool / unknown OS	Skipped with a one-line stderr notice

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

```markdown
| 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 |
| src/components/FreewordSearchFilter.tsx | 65 | 1 | useDocumentTypeSettingsQuery — React Query cache/fetch |
| src/components/FreewordSearchFilter.tsx | 70 | 1 | useMemo targetOptions — Deps change |
| src/components/FreewordSearchFilter.tsx | 119 | 1 | MultiSelectRHF render — User opens filter |

## Tools Used

| Tool | Purpose |
|------|---------|
| `gh pr diff` | Get PR diff |
| `git diff` | Get branch diff |
| Serena `find_symbol` | Locate functions |
| Serena `find_referencing_symbols` | Find callers (trace UP) |
| Serena `get_symbols_overview` | Map file structure |
| Serena `write_memory` | Save trace for future reference |
| `scripts/copy-to-clipboard.sh` | OS-aware clipboard copy of the extension table (pbcopy / wl-copy / xclip / xsel / clip.exe / clip; graceful skip otherwise) |

## 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