# Arch Lookup

> Look up Tensix architecture, instruction, or LLK implementation details across architectures. Orchestrates sage agents in parallel.

- Skill: `tenstorrent/arch-lookup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tenstorrent/arch-lookup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tenstorrent/arch-lookup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tenstorrent (https://skillmd.com/u/tenstorrent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tenstorrent/arch-lookup

---


# /arch-lookup — Architecture Documentation Lookup

## Usage

```
/arch-lookup "How does SFPMAD work?"
/arch-lookup "How does unpack handle Float16 on Blackhole?"
/arch-lookup "What is BroadcastType?"
/arch-lookup "How do T0/T1/T2 synchronize?"
```

## Step 1: Analyze the Query

Determine which architectures are relevant:
- **Specific architecture mentioned** → launch ONLY that sage
- **No architecture specified** → launch ALL relevant sages in parallel (up to 3)
- **Pure ISA question with no arch context** → launch sage-wormhole + sage-blackhole only (they have DeepWiki access). Skip sage-quasar unless Quasar is mentioned — tt-isa-documentation has no Quasar content.

## Step 1b: Classify Question Type (MANDATORY)

Before writing the sage prompt, classify the question. This determines which source the sage must consult **first** — otherwise the sage will default to grep and miss authoritative HW information.

| Question Type | Examples | Required Primary Source |
|---------------|----------|-------------------------|
| **HW capability / spec** | "What formats does X support?", "What SFPU instructions exist?", "How wide is the FPU?", "How many DEST rows?" | **Confluence (QSR) / DeepWiki (WH,BH) FIRST**, code second |
| **HW behavior / semantics** | "How does SFPMAD handle NaN?", "When does the pipeline stall?", "What does instruction X do in HW?" | **Confluence / DeepWiki FIRST**, code second |
| **LLK implementation** | "How is matmul implemented?", "What does llk_unpack_AB do?", "Where is X wired up?" | **Code FIRST** (`tt_llk_*/`), docs second |
| **Mixed / end-to-end** | "How is Float16 handled from unpack to pack?" | Both required — docs for HW limits, code for the software path |

**Critical distinction:** LLK code shows what is **wired up in software**. It can lag or diverge from what the **hardware actually supports**. For HW-capability / HW-behavior questions, a grep-only answer is incomplete — the authoritative source is Confluence (Quasar) or DeepWiki / tt-isa-documentation (WH, BH).

## Step 2: Launch Sage Agents

Launch up to 3 agents IN PARALLEL using the Agent tool:

| Agent | Scope | Primary ISA Source |
|-------|-------|--------------------|
| `sage-wormhole` | `tt_llk_wormhole_b0/` | DeepWiki + assembly.yaml |
| `sage-blackhole` | `tt_llk_blackhole/` | DeepWiki + assembly.yaml |
| `sage-quasar` | `tt_llk_quasar/` | Confluence + assembly.yaml (NO DeepWiki) |

**Prompt construction rules:**

1. Start with the user's exact question, verbatim.
2. **If the question is HW capability / behavior (per Step 1b), you MUST explicitly instruct the sage to consult docs first.** Example phrasing to include:
   > "This is a HW-capability question. Consult Confluence first (sage-quasar) / DeepWiki tt-isa-documentation first (sage-wormhole, sage-blackhole) to get the authoritative HW answer. Use code grep only to cross-verify what is actually wired up in the LLK. If docs and code disagree, call out the conflict — do not silently prefer one."
3. Do NOT over-constrain the sage prompt with code-only framing (e.g. "grep for the enum", "cite file:line for the definition") on HW-capability questions — that will push the sage into grep-only mode and bypass its doc-consultation protocol.
4. Always allow the sage to return both doc-sourced facts (with staleness caveats) and code-sourced facts (with file:line).

## Step 3: Aggregate

After all sages return:
1. **Commonalities** — what's consistent across architectures
2. **Differences** — architecture-specific variations (highlight these clearly)
3. **Synthesize** — unified explanation with per-arch sections where they diverge

## Quality Checklist

Before responding, verify:
- [ ] Question was classified per Step 1b; sage prompt matched the classification
- [ ] For HW-capability / HW-behavior questions, the sage cited Confluence (QSR) or DeepWiki / tt-isa-documentation (WH, BH) — not just code grep
- [ ] Where HW docs and LLK code disagree, the conflict is called out (code lagging HW is common)
- [ ] WHY explained — hardware constraints documented, not just code description
- [ ] Default path identified — baseline vs variants distinguished
- [ ] All data format paths covered
- [ ] Code references include file:line; doc references include Confluence URL + last-updated date (Quasar)
- [ ] Architecture differences highlighted where they exist