Explain

Quick Ref: Deep-dive explanation with code walkthrough. Output: .agents/research/YYYY-MM-DD-explain-{topic}.md

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Pre-flight: Git Safety Check

git status --short

If uncommitted changes exist:

AskUserQuestion with questions:
[
  {
    "question": "You have uncommitted changes. Commit before proceeding?",
    "header": "Git",
    "options": [
      {"label": "Commit first (Recommended)", "description": "Save current work so you can revert if this skill modifies files"},
      {"label": "Continue without committing", "description": "Proceed — I accept the risk"}
    ],
    "multiSelect": false
  }
]

If "Commit first": Ask for a commit message, stage changed files, and commit. Then proceed.

Step 1: Determine What to Explain

If the user provides a file path, read it directly. If they provide a feature or concept name, find the relevant code:

# Find files by name
Glob pattern="**/*FeatureName*.swift"

# Find files that mention the feature/concept
Grep pattern="FeatureKeyword" glob="**/*.swift" output_mode="files_with_matches"

# Find the entry point (view, view model, manager)
Grep pattern="struct.*FeatureName.*View|class.*FeatureName" glob="**/*.swift" output_mode="content"

Read every relevant file — don't explain code you haven't read.

Step 2: Explain — Overview

After reading the code, document:

What it is: [One paragraph summary — what this code does]

Why it exists: [The problem it solves or user need it fulfills]

Where it lives: [File paths, module/directory]

Step 3: Explain — Key Components

Identify the main types, protocols, and functions:

# List types defined in the target directory
Grep pattern="^(class|struct|enum|protocol|actor)\s+\w+" glob="**/*.swift" output_mode="content"

Present as a table:

Component	Purpose	Location
`ItemDetailViewModel`	Manages item display and editing state	Sources/Features/ItemDetail/ItemDetailViewModel.swift
`ItemDetailView`	SwiftUI view for displaying item details	Sources/Features/ItemDetail/ItemDetailView.swift

Step 4: Explain — How It Works

Trace the execution flow step by step. For each step, reference the actual code:

1. User taps item in list → ItemListView.swift:45
   NavigationLink triggers with selected item

2. ItemDetailView initializes → ItemDetailView.swift:12
   Creates ItemDetailViewModel with the item

3. View model loads data → ItemDetailViewModel.swift:28
   .task modifier calls loadItemDetails()

4. Details populated → ItemDetailViewModel.swift:35
   @Published properties updated, view re-renders

Use LSP for tracing definitions and references when available:

LSP operation="goToDefinition" filePath="path/to/file.swift" line=45 character=12
LSP operation="findReferences" filePath="path/to/file.swift" line=28 character=10

Step 5: Explain — Data Flow

Show how data moves between components:

[User Tap]
    ↓
ItemListView (NavigationLink)
    ↓ passes Item
ItemDetailView (creates view model)
    ↓ item reference
ItemDetailViewModel (@Published properties)
    ↓ async load
NetworkService.fetchDetails(item.id)
    ↓ returns DetailResponse
ItemDetailViewModel.details = response
    ↓ @Published triggers
ItemDetailView re-renders with details

Step 6: Explain — Dependencies

Upstream (what this code depends on)

# Find imports
Grep pattern="^import " path="<target_file>" output_mode="content"

# Find injected dependencies
Grep pattern="init\(" path="<target_file>" output_mode="content"

Downstream (what depends on this code)

# Find all files that reference this type
Grep pattern="TypeName" glob="**/*.swift" output_mode="files_with_matches"

Depends on: [list with file paths]

Depended on by: [list with file paths]

Step 7: Explain — Edge Cases & Gotchas

Look for:

Optional handling (what happens when data is nil?)
Error paths (what happens when network fails?)
Boundary conditions (empty lists, maximum values)
Concurrency considerations (actor isolation, main thread requirements)

Scenario	Behavior	Notes
Item has no category	Shows "Uncategorized"	Nil coalescing at ViewModel.swift:34
Network timeout	Shows cached data	Falls back to SwiftData query
Empty search results	Shows empty state view	Handled by ContentUnavailableView

Step 8: Check Git History

# When was this code written/last changed?
git log --oneline -5 -- "path/to/file.swift"

# Who authored the key implementation?
git log --format="%h %ai %s" -3 -- "path/to/file.swift"

Step 9: Display Results and Write Report

Display the full explanation inline (overview, components, flow, data flow, dependencies, edge cases) so the user sees results immediately.

Then write to .agents/research/YYYY-MM-DD-explain-{topic}.md for future reference.

Include a "Quick Reference" section at the end:

## Quick Reference

**To modify this feature:** Start at [primary file], the entry point is [function/view]

**To debug issues:** Check [key file:line] where [critical logic happens]

**To add tests:** Mock [protocol] and test [key methods]

Step 10: Follow-up

AskUserQuestion with questions:
[
  {
    "question": "Would you like to explore further?",
    "header": "Next",
    "options": [
      {"label": "Trace a specific path", "description": "Follow a particular code path in more detail"},
      {"label": "Generate tests", "description": "Create tests for this feature based on the explanation"},
      {"label": "Explanation is sufficient", "description": "No further questions"}
    ],
    "multiSelect": false
  }
]

Troubleshooting

Problem	Solution
Can't find the feature	Try broader search: `Grep pattern="keyword" glob="*/.swift"`
Feature spans many files	Start from the View, trace to ViewModel, then to Services
Code uses unfamiliar pattern	Explain the pattern inline — the user may not know it either
LSP not available	Fall back to Grep for finding references and definitions