Trace a feature from work item to code

This recipe walks through tracing a feature from its work item through the commits, PRs, and code it changed — using the cross-plane edges that connect Echo's three planes.

The question

You know a ticket number — say PROJ-412: "Rotate session tokens on privilege change" — and you want to understand what code it actually touched and why.

Step 1: Fetch the work item

curl -X POST "$ECHO_URL/projects/$PROJECT_ID/knowledge/fetch" \
  -H "X-API-Key: $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ref": "work_items:jira:PROJ-412" }'

The response includes the work item's content (title, description, status) and its relations — the cross-plane edges that link it to code and commits.

Step 2: Follow the relations

The relations array shows what this work item is connected to:

{
  "relations": [
    { "type": "resolved_by", "target": "commits:github:acme/api:def5678", "target_title": "fix: rotate session token on role downgrade" },
    { "type": "references", "target": "code:github:acme/api:main:src/auth/verify.ts:verifySession", "target_title": "verifySession" },
    { "type": "references", "target": "code:github:acme/api:main:src/auth/session.ts:rotateSession", "target_title": "rotateSession" }
  ]
}

Step 3: Fetch the commit

curl -X POST "$ECHO_URL/projects/$PROJECT_ID/knowledge/fetch" \
  -H "X-API-Key: $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ref": "commits:github:acme/api:def5678" }'

The commit's content includes the files changed, and its relations link back to the work item and forward to the code it modified.

Step 4: Fetch the code

Resolve each code ref to see the actual function, its signature, and its own graph neighborhood — callers, callees, and any tables it reads from or writes to.

Why this works

This trace is only possible because Echo models work items, commits, and code in one ontology with typed, directional relations. A search index can find files that mention "session token." Only a graph can answer "which code did this specific ticket change, through which commits?"

Next: Query a connected database.