trace

Savant verdict: Review advised

Security analysis or source-hub review identified patterns requiring attention.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

1 pattern found

• Agent Snooping: skills/shared/SKILL.mdmedium · SKILL.md:71 · Skill enumerates or reads other installed skills. Access to other skills' SKILL.md files or the skills directory reveals prompt instructions, capabilities, and secrets that should be invisible to peer skills.

Structure

• Description is very shortA description that says when to use the skill helps agents route to it.
• 2 referenced files aren't in the packagereferences/trace.feature, references/trace.featu. They may be binary, too large to catalog, or missing upstream.
• Ships 1 executable scriptscripts/validate.sh. Review what they do before enabling the skill for agents with tool access.
• No license declaredConfirm you may reuse this skill before importing it into your repository.
• The source hub's security checks flagged this skillSocket: warn (1 alert: gptSecurity)

SKILL.md

---
name: trace
description: Trace decisions through artifacts.
practices:
- distributed-tracing
- adr
- ebpf-observability
hexagonal_role: supporting
consumes: []
produces:
- result.json
context_rel:
- kind: shared-kernel
  with: curate
skill_api_version: 1
allowed-tools: Read, Grep, Glob, Bash
context:
  window: fork
  intent:
    mode: task
  sections:
    exclude:
    - HISTORY
  intel_scope: full
metadata:
  tier: knowledge
  dependencies:
  - curate
output_contract: 'stdout: decision provenance chain'
---
# Trace Skill

> **Quick Ref:** Trace design decisions through CASS sessions, handoffs, git, and artifacts. Output: `.agents/research/YYYY-MM-DD-trace-*.md`

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

## When to Use

- Trace HOW architectural decisions evolved
- Find WHEN a concept was introduced
- Understand WHY something was designed a certain way
- Build provenance chain for design decisions

For knowledge artifact lineage (learnings, patterns, tiers), use `$curate --mode=provenance` instead.

**CLI dependencies:** cass (session search). If cass is unavailable, skip transcript search and rely on git log, handoff docs, and `.agents/` artifacts for decision tracing.

## Execution Steps

Given `/trace <concept>`:

### Step 1: Classify Target Type

Determine what kind of provenance to trace:

```
IF target is a file path (contains "/" or "."):
  → Use `$curate --mode=provenance` (artifact lineage)

IF target is a git ref (sha, branch, tag):
  → Use git-based tracing (Step 2b)

ELSE (keyword/concept):
  → Use design decision tracing (Step 2a)
```

### Step 2a: Design Decision Tracing (Concepts)

Launch 4 parallel search agents (CASS, Handoff, Git, Research) and wait for all to complete.

**Backend:** Agents use `Task(subagent_type="Explore")` which maps to `task(subagent_type="explore")` in OpenCode. See `skills/shared/SKILL.md` ("Runtime-Native Spawn Backend Selection") for the shared contract.

Read `references/discovery-patterns.md` for agent definitions and prompts.

### Step 2b: Git-Based Tracing (Commits/Refs)

Read `references/discovery-patterns.md` for git-based tracing commands.

### Step 3: Build Timeline

Merge results from all sources into a single chronological timeline (oldest first). Deduplicate same-day/same-session events. Every claim needs a source citation.

### Step 4: Extract Key Decisions

For each event in timeline, identify:
- **What changed:** The decision or evolution
- **Why:** Reasoning if available
- **Who:** Session/author/commit author
- **Evidence:** Link to source (session path, file, commit)

### Step 5: Write Trace Report

**Write to:** `.agents/research/YYYY-MM-DD-trace-<concept-slug>.md`

Read `references/report-template.md` for the full report format and deduplication rules.

### Step 6: Report to User

Tell the user:
1. Concept traced successfully
2. Timeline of evolution (key dates)
3. Most significant decisions
4. Location of trace report
5. Related concepts to explore

## Handling Edge Cases

Read `references/edge-cases.md` for handling: no CASS results, no handoffs, ambiguous concepts (>20 results), and all-sources-empty scenarios. General principle: continue with remaining sources and note gaps in the report.

## Key Rules

- **Search ALL sources** - CASS, handoffs, git, research
- **Build timeline** - chronological evolution is the goal
- **Cite evidence** - every claim needs a source
- **Handle gaps gracefully** - not all concepts are in all sources
- **Write report** - trace must produce `.agents/research/` artifact

## Relationship to Artifact Provenance

| Skill | Purpose | Input | Output |
|-------|---------|-------|--------|
| `$curate --mode=provenance` | Artifact lineage | File path | Tier/promotion history |
| `/trace` | Design decisions | Concept/keyword | Timeline of evolution |

Use `$curate --mode=provenance` for: "Where did this learning come from?"
Use `/trace` for: "How did we decide on this architecture?"

## Examples

```bash
# Trace a design decision
/trace "three-level architecture"

# Trace a role/concept
/trace "Chiron"

# Trace a pattern
/trace "brownian ratchet"

# Trace a feature
/trace "parallel wave execution"
```

### Tracing an Architectural Decision

**User says:** `/trace "agent team protocol"`

**What happens:**
1. Agent classifies target as concept (not file path or git ref)
2. Agent launches 4 parallel agents: CASS search, handoff search, git log search, research artifact search
3. CASS finds 8 sessions mentioning "agent team", handoff finds 2 docs, git finds 3 commits, research finds 1 analysis
4. Agent builds chronological timeline from 2026-01-15 (first mention) to 2026-02-08 (latest update)
5. Agent extracts 5 key decisions: initial SendMessage design, TeamCreate addition, deliberation protocol, in-process mode, delegate mode
6. Agent writes trace report to `.agents/research/2026-02-13-trace-agent-team-protocol.md` with full timeline and citations

**Result:** Complete evolution timeline showing how agent team protocol developed across 7 sessions with source citations.

### Tracing from Git Commit

**User says:** `/trace abc1234`

**What happens:**
1. Agent detects git ref format (short sha)
2. Agent runs git-based tracing commands to get commit details, changed files, related commits
3. Agent uses `git log --grep` to find related work
4. Agent searches `.agents/` for contemporary research/plans
5. Agent builds timeline focused on that specific change
6. Agent writes report showing commit context, what changed, why (from commit message and related docs)

**Result:** Trace report links commit to broader design context from surrounding artifacts.

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| CASS returns no results | Session search not installed or query too specific | Check `which cass`. If missing, skip CASS and rely on handoffs/git/research. Try broader query terms. |
| Timeline has gaps | Not all decisions documented in searchable artifacts | Note gaps in report. Suggest interviewing team members or checking Slack/email archives for missing context. |
| Too many results (>50 matches) | Very broad concept or high-frequency term | Read `references/edge-cases.md` for ambiguous concept handling. Narrow query or filter by date range. Ask user for more specific aspect to trace. |
| Empty trace report (all sources failed) | Concept genuinely undocumented or typo | Verify spelling. Try synonyms. Report to user: "No documented history found. This may be a new concept or may need different search terms." |

## Reference Documents

- [references/trace.feature](references/trace.feature) — Executable spec: target-type routing, parallel multi-source search, cited chronological timeline, key-decision extraction, report + graceful gaps (soc-qk4b)
- [references/discovery-patterns.md](references/discovery-patterns.md) — Search-agent definitions and git-based tracing commands
- [references/report-template.md](references/report-template.md) — Trace report format and deduplication rules
- [references/edge-cases.md](references/edge-cases.md) — Empty/ambiguous source handling