Trace

Technical Context

• Core methodology: State table tracking at each step
• Domain adapters: Code, skills, workflows, documents
• Trace tables: Structured format for variable/state tracking
• Effectiveness: 60-80% detection rate for logic errors (vs 0% for testing)
• Integration: /code skill Phase 3.5 delegates to /trace code:<file>

Architecture Alignment

• Independent skill with domain adapters
• /code skill delegates TRACE phase to /trace code:<file>
• Can be invoked standalone or by other skills (/refactor, /av, /q)
• Extensible: New domain adapters added without core changes

Modes

/trace operates in 4 domain modes:

Visualization Features

TRACE reports include automatic visualization generation: Mermaid flowcharts, call graph recommendations (pyan), program slicing recommendations, and pre-built templates.

See references/visualization-features.md for full details on all 4 visualization types and usage instructions.

debugRCA Integration

TRACE integrates with debugRCA for enhanced root cause analysis: evidence saturation detection, red flag detection, ACH scenario generation, timeline visualization, call graph hypothesis generation, CKS findings persistence, and differential TRACE.

See references/debugrca-integration.md for all 7 integration features with code examples and benefits table.

Your Workflow

Step 1: Parse Target

Extract domain and target from invocation:

/trace code:src/handoff.py        -> domain=code, target=src/handoff.py
/trace skill:skill-development     -> domain=skill, target=skill-development
/trace workflow:flows/feature.md   -> domain=workflow, target=flows/feature.md
/trace document:CLAUDE.md          -> domain=document, target=CLAUDE.md

Default invocation (no domain specified):

• If target is .py file -> code domain
• If target is SKILL.md -> skill domain
• If target is in flows/ -> workflow domain
• Otherwise -> document domain

Step 2: Select Domain Adapter

ADAPTERS = {
    'code': CodeTracer,
    'skill': SkillTracer,      # Future: Extension point
    'workflow': WorkflowTracer, # Future: Extension point
    'document': DocumentTracer, # Future: Extension point
}

Step 3: Load Target File

CRITICAL: Read the target file before creating trace tables.

Step 4: Define Scenarios

For each target, define 3 scenarios:

1. Happy path: Normal operation
2. Error path: Exception/failure handling
3. Edge case: Boundary condition, timeout, empty input

Step 5: Create State Table

| Step | Operation | State/Variables | Resources | Notes |
|------|-----------|-----------------|-----------|-------|
| 1 | Initial state | var1=None, var2=[] | fd=None | Setup |
| 2 | Open file | var1=<fileobj> | fd=3 | File opened |
| 3 | Process data | var1=<data>, var2=[1,2,3] | fd=3 | Data processed |
| 4 | Close file | var1=None | fd=None | Cleanup |

Step 6: Trace Each Scenario

Step through the code/content line-by-line:

• Record state changes at each step
• Track resource acquisition/release
• Check cleanup in all paths (especially exception paths)
• Document any logic errors found

Step 7: Document Findings

See references/workflow-and-report-format.md for the full TRACE report template with executive summary, findings format, and results structure.

Validation Rules

• Before tracing: Read the target file completely
• During tracing: Cite line numbers for all findings
• After tracing: Verify all three scenarios traced
• No fabrication: Only report what you actually see in the code

Execution Directive

For /trace requests, execute this workflow:

cd P:/.claude/skills/trace && python __main__.py "domain:target"

# Examples
python __main__.py "code:src/handoff.py"
python __main__.py "skill:skill-development"
python __main__.py "workflow:flows/feature.md"
python __main__.py "document:CLAUDE.md"

Domain-Specific Behavior

Each domain has specific focus areas, trace table columns, checklists, and example invocations.

See references/domain-adapters.md for detailed checklists and trace table formats for all 4 domains (code, skill, workflow, document).

Integration with /code Skill

The /code skill Phase 3.5 (TRACE) delegates to /trace code:<file>. The delegation pattern and references to TRACE methodology, templates, and checklists are documented in references/integrations-and-usage.md.

Usage

# Code TRACE (fully implemented)
/trace code:src/handoff.py                    # Manual code trace-through
/trace code:src/handoff.py --template 2      # Use specific template
/trace code:src/handoff.py --no-tot           # Disable ToT enhancement

# Skill / Workflow / Document TRACE (extension points - future)
/trace skill:skill-development                # Intent detection review
/trace workflow:flows/feature.md              # Dependency verification
/trace document:CLAUDE.md                     # Consistency check

# Auto-detect domain (default behavior)
/trace src/handoff.py                         # Detects: code
/trace SKILL.md                                # Detects: skill
/trace flows/feature.md                       # Detects: workflow

Files

• SKILL.md - Skill definition (this file)
• __main__.py - Entry point with CLI argument parsing
• core/tracer.py - Core TRACE methodology
• core/state_table.py - State table creation
• adapters/code_tracer.py - Code TRACE adapter (implemented)
• adapters/skill_tracer.py - Skill TRACE adapter (extension point)
• adapters/workflow_tracer.py - Workflow TRACE adapter (extension point)
• adapters/document_tracer.py - Document TRACE adapter (extension point)
• templates/TRACE_METHODOLOGY.md - Domain-agnostic TRACE guide
• templates/code/TRACE_TEMPLATES.md - Code TRACE templates (5 templates)
• templates/code/TRACE_CHECKLIST.md - Code TRACE checklist (100+ checks)
• templates/code/TRACE_CASE_STUDIES.md - Real-world bug examples

Reference Files

Success Criteria

• Code TRACE works (all 5 templates functional)
• TRACE reports generated with findings
• Line numbers cited for all issues
• Three scenarios traced (happy, error, edge)
• Integration with /code skill Phase 3.5
• Skill / Workflow / Document TRACE adapters (future extension)