| name | arch-lookup |
| description | Look up Tensix HW behavior across architectures specifically to inform tt-emule mock implementations. Orchestrates per-arch sage agents in parallel and aggregates results with emule-mapping context. |
| user_invocable | true |
/arch-lookup — Architecture lookup for tt-emule mock work
When you're implementing (or debugging) a mock API in tt-emule, you
need to know what the real silicon does. This skill orchestrates
parallel sage-{wormhole,blackhole,quasar} agents that consult
DeepWiki + Confluence + LLK source, then aggregates the result with
an emule-simulation perspective.
Adapted from tt-metal/tt_metal/tt-llk/.claude/skills/arch-lookup
for the emule mock-API workflow.
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?"
/arch-lookup "How does noc_async_write_multicast complete on receivers?"
/arch-lookup "What does llk_unpack_AB_init actually configure?"
Two flavors of question this skill is for:
- Mock-faithfulness — "I'm about to implement / am implementing
a stub for X. What does the real HW do, so my mock matches?"
- Correctness debug — "Emule's output for op Y doesn't match
silicon / torch. Where in the HW pipeline could the mock be diverging?"
Step 1 — Analyze the query
Which architectures are relevant?
- Specific arch mentioned → launch ONLY that sage.
- No arch specified + HW spec question → launch
sage-wormhole + sage-blackhole (they have DeepWiki access). Skip sage-quasar
unless Quasar is mentioned — tt-isa-documentation has no Quasar
content.
- Cross-arch comparison wanted → launch all 3.
- emule already mocks X, I want to know if it's right → at minimum
launch the arch that matches the active test config
(
TT_EMULE_ARCH if explicitly set; otherwise follow the project
default of wormhole n150 unless the caller/test specifies another arch).
Step 1b — Classify question type (MANDATORY)
This determines what each sage must consult FIRST — otherwise the
sage defaults to grep and misses the authoritative HW source.
| Question type | Examples | Required primary source |
|---|
| HW capability / spec | "What formats does X support?", "How many DEST rows?", "Does Blackhole have FP8?" | DeepWiki (WH/BH) / Confluence (QSR) FIRST, code second |
| HW behavior / semantics | "How does SFPMAD handle NaN?", "When does pipeline stall?" | DeepWiki / Confluence FIRST, code second |
| LLK implementation | "How is matmul wired up?", "Where is X called?" | Code FIRST (tt_llk_*/), docs second |
| Mixed / end-to-end | "How is Float16 handled unpack → math → pack?" | Both required |
| emule mock review | "Is my noc_traits_t faithful?" | HW spec FIRST, then existing emule mock at tt-emule/include/jit_hw/, then propose changes |
Critical: LLK code shows what is wired up in software; it can lag
or diverge from what the hardware supports. For HW-capability /
HW-behavior questions, a grep-only answer is incomplete.
Step 2 — Launch sage agents
Launch up to 3 agents IN PARALLEL via the Agent tool:
| Agent | LLK 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), include
the explicit instruction:
"This is a HW-capability question. Consult DeepWiki
tt-isa-documentation FIRST (sage-wormhole/blackhole) or
Confluence FIRST (sage-quasar). Use code grep only to cross-verify
what is wired up in LLK. If docs and code disagree, call out the
conflict — do not silently prefer one."
- Always include in the sage prompt:
"After describing what silicon does, conclude with an 'Emule
mapping' section: does tt-emule's mock at
include/jit_hw/ exist
today? If yes, is it faithful? If no, recommend the smallest
mock that would suffice (which file, what guard
pattern — see tt-emule/.claude/references/emule-mapping.md for
the strategies catalog)."
- Do NOT over-constrain the sage prompt with code-only framing
("grep for the enum", "cite file:line for the definition") on
HW-capability questions — that pushes the sage into grep-only mode
and bypasses doc consultation.
- 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 — arch-specific variations (highlight clearly)
- Emule status snapshot — for each arch, what does emule's mock
look like today, and where does it diverge from silicon?
- Synthesis — unified explanation with per-arch sections where
they diverge, and a "what to do in emule" recommendation if the
question was implementation-oriented.
Step 4 — Final response shape
# {topic}
## TL;DR
[2-3 sentence answer combining the arch findings]
## Hardware behavior (per arch)
### Wormhole B0
[…]
### Blackhole
[…]
### Quasar (if launched)
[…]
## Cross-arch differences
[Where the archs diverge — highlight if it affects emule's choices]
## Emule today
[What tt-emule's mock currently does, file:line at jit_hw/. If
nothing exists, say so.]
## Recommendation (if implementation question)
[Smallest faithful mock: file path, signature, guard pattern (per-op
patch / semantic rewrite / stub-in-jit_hw — see emule-mapping.md).]
Quality checklist
Before responding, verify:
Related skills
/implement-mock — workflow for stubbing a silicon API after this
lookup tells you what it should do.references/emule-mapping.md — catalog of HW concept → emule
simulation strategy mappings.
