---
name: lc-context
description: >
  Use whenever working in a project that has a `.linear_canal_data/` folder —
  this signals Linear Canal has indexed the codebase. Invoke before any Glob,
  Grep, or raw file reads. Covers: "how does X work", "where is Y defined",
  "what files handle Z", explaining architecture, fixing bugs, adding features,
  or any file edit. The ctx files contain pre-compiled insights — reading them
  first saves 80-95% of tokens vs raw source exploration. If you see
  `.linear_canal_data/` in the project root, use this skill first.
---

# Linear Canal — lc-context

Linear Canal has indexed this codebase into pre-compiled `.ctx` files. Reading
them costs 200–800 tokens each instead of the thousands you'd spend walking raw
source files.

---

## Step 0 — Find the project ID

The project ID is the directory name inside `.linear_canal_data/`. Find it with:

```
Bash: ls .linear_canal_data/
```

All ctx files live at:
```
.linear_canal_data/<project_id>/ctx/
```

---

## The ctx files

Read these in order — stop when you have enough context.

### 1. `ARCHITECTURE.ctx` — always read first
Full module map, entry points, tech stack, file counts per module, deployment
notes. Answers most "where does X live" questions without opening a single source
file.

```
Read: .linear_canal_data/<project_id>/ctx/ARCHITECTURE.ctx
```

### 2. `INTERFACES.ctx` — find any exported symbol
Every exported function, class, and method across the codebase, grouped by
module. Use when you know the symbol name but not the file.

```
Read: .linear_canal_data/<project_id>/ctx/INTERFACES.ctx
```

### 3. `RISKS.ctx` — before editing anything
Files flagged for LONG_FUNCTION, SILENT_ERROR, NO_TEST_COVERAGE, STALE_TODO —
with exact paths and line numbers. Read this before touching a file so you know
what to watch out for.

```
Read: .linear_canal_data/<project_id>/ctx/RISKS.ctx
```

### 4. `DEPENDENCIES.ctx` — before adding imports
Module dependency graph and breaking-change edges. Read before adding a new
import or creating a cross-module dependency.

### 5. `PATTERNS.ctx` — before writing new code
Detected design patterns (FACTORY, SINGLETON, MIDDLEWARE, etc.) with the files
where they're used. Helps you match the project's conventions.

### 6. `<module>.ctx` — deep dive into one module
When ARCHITECTURE.ctx tells you which module to look at, read that module's own
ctx file for detailed context: purpose, public interface, risks, full file list.

```
Read: .linear_canal_data/<project_id>/ctx/<module_name>.ctx
```

---

## Recommended workflow

```
1. Bash: ls .linear_canal_data/              → get project ID
2. Read ARCHITECTURE.ctx                     → orient (~400 tokens)
3. Identify relevant module(s)
4. Read <module>.ctx                         → deep context (~300 tokens)
5. Read INTERFACES.ctx if you need a symbol  → (~500 tokens)
6. Read RISKS.ctx for any file you'll edit
7. Only then open raw source files — and only the specific ones needed
```

Total: ~1,500 tokens for full project understanding vs 10,000–50,000 for raw exploration.

---

## MCP tools

If the Linear Canal MCP server is running (auto-started via `.mcp.json` when
the plugin is installed, or manually via `linear-canal serve`), you have three
additional tools:

### `lc_search` — semantic search
Searches Qdrant vector collections for natural-language queries.
```
lc_search("user authentication JWT token validation", limit=5, tier="HIGH")
```
Use when you need the exact location of a concept and ARCHITECTURE.ctx gave you
the module but not the line.

### `lc_impact` — change impact before editing
```
lc_impact(file_path="src/services/auth.py")
```
Returns: dependents, coupling score, related modules, test coverage. Call this
before editing any file that might have downstream effects.

### `lc_context` — task-specific context bundle
```
lc_context(
  task_description="add rate limiting to the API authentication endpoint",
  token_budget=8000
)
```
Returns the most relevant ctx + code chunks for a specific task, pre-filtered
to your token budget. Best entry point for complex multi-file tasks.

**If MCP tools aren't available** (server not running), fall back to the ctx
file workflow above — it covers ~90% of the same ground.

---

## Token economics

| Approach | Tokens | Signal |
|---|---|---|
| Glob + read all source files | 20k–100k | High noise |
| ARCHITECTURE + module ctx | 600–1,500 | Focused |
| `lc_context()` for a task | 2k–8k | Targeted |
| `lc_search()` for a symbol | 200–500 | Precise |

---

## File reference

```
.linear_canal_data/<project_id>/
  ctx/
    ARCHITECTURE.ctx    ← start here always
    INTERFACES.ctx      ← find any export
    RISKS.ctx           ← before editing
    DEPENDENCIES.ctx    ← before importing
    PATTERNS.ctx        ← before adding code
    OWNERSHIP.ctx       ← coupling / owners
    <module>.ctx        ← per-module deep dive
  scores.json           ← per-file importance scores
  graph.db              ← SQLite graph store

.LC/
  CLAUDE.md             ← agent instructions (Claude Code / Kilo / Roo)
  AGENTS.md             ← agent instructions (OpenCode / universal)
  GEMINI.md             ← agent instructions (Gemini CLI)
  .cursorrules          ← agent instructions (Cursor)
```
