arch-lookup

/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:

1. Mock-faithfulness — "I'm about to implement / am implementing

a stub for X. What does the real HW do, so my mock matches?"

1. 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.

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:

Prompt construction rules:

1. Start with the user's exact question, verbatim.
2. 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."

1. 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)."

1. 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.

1. 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 — arch-specific variations (highlight clearly)
3. Emule status snapshot — for each arch, what does emule's mock

look like today, and where does it diverge from silicon?

1. 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:

• [ ] Question was classified per Step 1b; sage prompt matched
• [ ] For HW-capability questions, sages cited DeepWiki / Confluence,

not just code grep

• [ ] Where HW docs and LLK code disagree, conflict is called out
• [ ] Default path identified — baseline vs variants distinguished
• [ ] All relevant data format paths covered
• [ ] Code refs include file:line; doc refs include Confluence URL +

last-updated date (Quasar)

• [ ] Emule mapping section present — what's the current mock?

where would changes go?

• [ ] If a recommendation was given, it cites the strategy from

tt-emule/.claude/references/emule-mapping.md (per-op patch / semantic rewrite / stub-in-jit_hw)

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.