choose-artifact

Choose Artifact

Use this skill when the user is at the entry point of a chip frontend project (or a new component within one) and must decide which artifact(s) to build, in which order, with what fidelity. Do not autoload — only respond when the user invokes /chipdev-method:choose-artifact or matches the trigger phrases in the description.

The job here is judgment delivery, not chapter recitation. Give the user a decision, not a survey.

---

How to use this skill in a response

When triggered:

1. Confirm the user's situation in one sentence (new chip vs. new module inside an existing project; greenfield vs. RTL-already-exists; etc).
2. Walk them through the decision tree below — answer their actual question, do not dump all sections.
3. Cite the relevant invariants that drive the recommendation.
4. Surface the most likely failure mode for the path you recommend.
5. End with the next-step skill to route to (define-contracts, build-*, etc).

Keep the response under ~400 words unless the user asks for depth.

---

Three artifacts at a glance [abstract]

Dimension	Behavior model	Performance model	RTL
Goal	Functional / ISA correctness	Microarchitecture timing	The actual hardware
Fidelity	Architectural state	Cycle-level	Bit + cycle + synthesizable
Speed	10×–100× hardware	0.001×–0.01×	< perf model
Build cost	Low	High	Highest
Primary consumer	Driver / SW team, difftest reference	Microarch exploration, perf analysis	Tape-out, verification sign-off
When required	Always (somewhere — even if it's just a Python golden)	When microarch decisions need quantitative answers	Always, eventually

This three-way split is the central frame. Most other decisions cascade from it.

---

Decision tree [abstract]

Ask the user three questions. Recommend based on answers.

Q1. What is the immediate goal?

• Validate functionality of a new ISA / new dataflow → start with behavior model. Behavior model is cheapest to build and converges fastest with software/driver work.
• Explore microarchitecture trade-offs (pipeline depth, cache size, NoC topology) → start with performance model scoped to the subsystem under question.
• Sign off RTL for tape-out → you need RTL plus at least one of the above as a reference. Decide which reference based on what you already have.

Q2. Do you need behavior↔RTL difftest?

• Yes → behavior model and RTL must share an interface contract from day one. Route to define-contracts before either implementation begins.
• No (e.g., perf-only project, no tape-out) → performance model can drift from RTL contracts without immediate harm; lower coordination overhead.

Q3. What's your compute and time budget?

• Single engineer, weeks → pick one artifact only. Behavior model first if unsure. Resist the urge to build all three.
• Team, months → all three are feasible in parallel if contracts are defined first (otherwise you ship three incompatible artifacts).
• Greenfield with no spec yet → write the spec as a DSL (see define-contracts) before any implementation. Spec drift is cheaper to prevent than to repair.

---

Six invariants [abstract]

Six principles cut across all three artifacts. Apply them when choosing AND when implementing. Detailed breakdown in references/six-invariants.md.

1. Generation over hand-writing. Anything that can be derived from a formal source (interface, hierarchy, register layout) should be generated. Hand-writing connection code does not scale past ~10 modules.
2. Contract over convention. Interfaces are formal, with explicit protocol annotations (valid / valid+ready / no-handshake). Naming conventions are not a contract.
3. Composition over inheritance. Aggregate subsystems by composition. Reserve inheritance for the single line GeneratedBase → HandwrittenImpl.
4. Configuration over hard-coding. Sim interval, idle threshold, dump filters, MMIO map — all in JSON / TOML / YAML, not code.
5. Sparse over preallocated. Memory and resources allocate on first touch. Support large address spaces without committing memory upfront.
6. Determinism over concurrency. Schedule modules in a fixed sequential order under a non-blocking advance(cycles) contract. Avoid SC_THREAD- style coroutines unless the workload genuinely requires them.

When recommending an artifact path, point out which of these invariants is most at risk on that path. Most failure modes trace back to violating one of these six.

---

Common failure modes [abstract]

• Building all three at once with no shared contract. Three teams produce three incompatible artifacts; integration costs more than building any one of them. Mitigation: enforce define-contracts before any build-* skill.
• Performance model masquerading as a behavior model. A cycle-accurate model gets used as the difftest reference, but its timing-introduced side effects (e.g., cache state) leak into the architectural state, causing false-positive difftest mismatches. Mitigation: separate the two roles (build-behavior-model is explicit about what to keep / drop).
• Behavior model with no probes. A behavior model is built without thinking about difftest, then probes are bolted on later — usually with timing-coupling that destroys the cycle-independence the behavior model was supposed to provide. Mitigation: pre-embed probes (see build-behavior-model and define-contracts).
• RTL written before contracts. Module ports are decided ad hoc per module; integration discovers protocol mismatches; refactor wave in Phase 4. Mitigation: contracts first.
• Skipping the spec-as-DSL step. Spec lives in spreadsheets or wiki; every artifact re-encodes it; drift is inevitable. Mitigation: even a minimal DSL is better than three hand-coded copies.

---

Roadmap pattern [industry-pattern]

A typical sequence of phases (durations vary by team size; the order is what matters):

Phase 0 — Infrastructure: build system, DSL toolchain, framework skeleton.
Phase 1 — End-to-end thin slice through the data path on minimal config.
Phase 2 — Compute units to bit-accuracy; align floating-point ULP with RTL.
Phase 3 — All modules stubbed; connection code generated; compiles clean.
Phase 4 — Functional completeness: caches, multi-instance, real workloads.
Phase 5 — Hardening: cycle-accuracy alignment with RTL, perf optimization.
Phase 6 — Maintenance: CI gates, RTL drift tracking, version pinning.

Milestones M0–M5 typically map to the end of Phase 0–5. The exact week counts depend on team size and complexity.

Detailed phase content in references/roadmap-phases.md.

---

Team roles [abstract]

For a team-scale effort, four roles are usually needed. For a solo effort, one engineer wears all four hats but should still keep the role boundaries in mind:

• Architect — owns the DSL, framework layer, code generation pipeline. Must understand both the target microarchitecture and parser-generator toolchains.
• Framework engineer — owns the simulation kernel, memory subsystem, build system. Needs strong CMake / language-tooling skills.
• Module engineer — owns one or more hardware blocks at cycle-accurate fidelity. Must read the corresponding RTL.
• Verification engineer — owns test vectors, golden comparison, CI pipelines, regression gates.

---

See also

• define-contracts — the next skill if any artifact is being built.
• build-perf-model / build-behavior-model / build-rtl — the per-artifact construction skills.
• align-and-difftest — when behavior model and RTL must agree.
• references/decision-matrix.md — long-form decision matrix.
• references/six-invariants.md — long-form invariants with examples.
• references/roadmap-phases.md — long-form phase descriptions and milestones.