| name | choose-artifact |
| description | Helps the user decide whether to build a performance model, a behavior model, or RTL for a chip frontend task, and in what order. Activate when the user explicitly invokes /chipdev-method:choose-artifact, or asks variants like "should I write cmodel or RTL first", "怎么选模型", "what artifact do I need", or stands at the start of a new chip / module / subsystem and has not yet committed to an artifact path. |
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:
- Confirm the user's situation in one sentence (new chip vs. new module
inside an existing project; greenfield vs. RTL-already-exists; etc).
- Walk them through the decision tree below — answer their actual
question, do not dump all sections.
- Cite the relevant invariants that drive the recommendation.
- Surface the most likely failure mode for the path you recommend.
- 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.
- 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.
- Contract over convention. Interfaces are formal, with explicit
protocol annotations (valid / valid+ready / no-handshake). Naming
conventions are not a contract.
- Composition over inheritance. Aggregate subsystems by composition.
Reserve inheritance for the single line
GeneratedBase → HandwrittenImpl.
- Configuration over hard-coding. Sim interval, idle threshold, dump
filters, MMIO map — all in JSON / TOML / YAML, not code.
- Sparse over preallocated. Memory and resources allocate on first
touch. Support large address spaces without committing memory upfront.
- 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.
