By name: arch-lookup description: Look up Tensix architecture, instruction, or LLK implementation details across architectures. Orchestrates sage agents in parallel. user_invocable: true
/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:
- Start with the user's exact question, verbatim.
- 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."
- 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.
- 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:
- Commonalities — what's consistent across architectures
- Differences — architecture-specific variations (highlight these clearly)
- 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