rf-design

name	rf-design
description	Design and verify an RF/mmWave block (LNA, mixer, VCO, PLL, PA): topology selection and matching, S-parameter, harmonic-balance, Pnoise/PAC, IP3, and load-pull analyses, signed off against the RF spec table across corners. Use when designing or re-running an RF block. Loop-backs are stage-local first (spec/stability → topology_matching, convergence → harmonic_balance); when a cap is exhausted RF opens a cross-domain fix_request (circuit-design for device rework, em-modeling for a passive shortfall) and reads the EM-modeling passive model as a data dependency.
version	1.0.0
author	chuanseng-ng
license	MIT
allowed-tools	Read, Write, Bash

Skill: RF / mmWave Design

Invocation

• If invoked by a user presenting an RF design task: immediately spawn the analog-chip-design-agents:rf-design-orchestrator agent and pass the full user request and any available context. Do not execute stages directly.
• If invoked by the rf-design-orchestrator mid-flow (including re-validation after a serviced fix_request): do not spawn a new agent. Treat this file as read-only — return the requested stage rules, sign-off criteria, or loop-back guidance.

Spawning the orchestrator from within an active orchestrator run causes recursive delegation and must never happen.

Pre-run Context

Before executing or advising on any stage, read the following if they exist:

1. memory/rf/knowledge.md — known matching/stability fixes, HB convergence recipes, phase-noise and load-pull patterns, and PDK/tool quirks. Incorporate its guidance into every stage.
2. memory/rf/run_state.md — current run identity for resume-after-interruption.

Purpose

Design and verify an RF/mmWave block — select and match the topology, extract S-parameters, run harmonic-balance / Pnoise / IP3 / load-pull, and sign off against the RF spec table across the required corners. Seven stages with explicit QoR gates. RF design is a cross-domain producer — its loop-backs are stage-local first (spec/stability fail → topology_matching; non-convergence → harmonic_balance settings); when a stage-local cap is exhausted and the block still misses spec it opens a cross-domain fix_request. It reads the EM-modeling passive model (Touchstone + fitted lumped model) from design_state.em as a data dependency; a limiter traced to a passive opens a fix_request with route_to: em-modeling (an automated EM re-solve), while a device-level spec miss opens one with route_to: circuit-design. The pipeline-orchestrator re-validates the fix via this orchestrator.

---

Supported EDA Tools

Open-Source

• Qucs-S (qucs-s) — schematic + harmonic-balance front-end (RF capable)
• Xyce (xyce) — parallel SPICE with harmonic balance
• ngspice (ngspice) — small-signal / transient (limited native RF)
• scikit-rf (Python skrf) — S-parameter math, stability (K/Δ), de-embedding
• openEMS (openEMS) — passive co-reference / S-param cross-check

Proprietary (detect-only — never installed)

• Cadence Spectre RF (spectre) — S-param/HB/Pnoise/PAC/load-pull
• Keysight ADS / GoldenGate (ads)
• Cadence AWR Microwave Office (awr)
• Synopsys HSPICE-RF (hspice)
• AFS-RF (Analog FastSPICE RF)

---

Stage: rf_spec

Domain Rules

1. Read the RF block intent (block class LNA/mixer/VCO/PLL/PA, frequency band, source/load impedance, supply) and the target spec table from constraints.rf_specs (preferred) or constraints.specs; record which specs are in scope for the block class (PA → pae_pct / p1db_dbm / evm_pct; VCO/PLL → phase_noise_dbc_hz; LNA/mixer → nf_db / gain_db / s11_db_max / iip3_dbm).
2. Bind the passive data dependency: if the block uses on-chip inductors/transformers/lines, read design_state.em.touchstone + design_state.em.fitted_model; if absent, treat the passive as ideal/approximate and flag the assumption for later escalation.
3. Build the corner set from constraints.corners (process × voltage_pct × temp_c) and the analysis frequency grid covering the band plus the harmonics of interest.

QoR Metrics to Evaluate

• All block-relevant rf_specs present and bounded
• Passive model bound from design_state.em, or explicitly flagged as ideal
• Corner / frequency grid covers the band + the harmonics needed downstream

Common Issues & Fixes

Issue	Fix
No rf_specs for the block class	escalate constraint_gap — require the governing RF spec(s) before proceeding
EM passive model missing for an on-chip inductor	read design_state.em; if absent, flag the ideal-passive assumption and WARN (may drive a later escalation)

Output Required

• RF spec table (block class, in-scope specs + targets, band, source/load Z, passive-model binding, corner/frequency grid)

---

Stage: topology_matching

Domain Rules

1. Select/confirm the topology for the block class and synthesize input/output (and inter-stage) matching networks toward the target source/load impedance, using the bound EM passive models where on-chip passives are used (read Q/SRF from design_state.em).
2. Verify the matching network trends s11/s22 toward rf_specs.s11_db_max in-band and does not push any passive past its self-resonant frequency.
3. This is the loop-back target: on a downstream spec/stability fail, re-enter here to re-match or re-top (max 2×).

QoR Metrics to Evaluate

• In-band input/output match trending to s11_db_max
• Matching components within passive Q/SRF limits
• Topology supports every in-scope spec

Common Issues & Fixes

Issue	Fix
Match operating above a passive's SRF	re-select / re-match below SRF; if no on-chip option exists, open fix_request → em-modeling for a re-solve
Cannot hit s11_db_max with the chosen topology	re-top (loop-back target) — add a matching section or change topology class

Output Required

• Topology choice + matching-network netlist with component values and the referenced passive models

---

Stage: sparameter_analysis

Domain Rules

1. Run small-signal S-parameter analysis across the band/corners; extract s11/s22 (return loss), s21 (gain), and compute the Rollett stability factor K (and B1/Δ) from the S-matrix with scikit-rf.
2. Read S-params from the tool summary / Touchstone file, never raw frequency dumps; flag any non-passive S-matrix as a tool/setup error.
3. Where on-chip passives are used, confirm the S-params reflect the EM-fitted model (not an ideal substitute).

QoR Metrics to Evaluate

• s11_db/s22 ≤ rf_specs.s11_db_max in-band
• gain_db (S21) ≥ target
• k_factor ≥ 1 in-band where unconditional stability is required

Common Issues & Fixes

Issue	Fix
K < 1 (potentially unstable) in-band	loop back → topology_matching: add stabilization / re-match
Return loss misses s11_db_max	loop back → topology_matching: re-tune the matching network

Output Required

• S-parameter / Touchstone results + stability table (s11_db, s22, gain_db/S21, k_factor per corner)

---

Stage: harmonic_balance

Domain Rules

1. Run harmonic-balance (Qucs-S / Xyce HB; Spectre RF if detected) for large-signal behaviour — gain compression, conversion gain (mixer), oscillation/tuning (VCO); set tone count/order and oversampling adequate for the spectral content.
2. On non-convergence, this is the convergence loop target: re-run with adjusted HB settings (more harmonics, source stepping, continuation) — max 2×.
3. Read the HB summary (p1db_dbm, compression, harmonic levels) from the tool summary file, not the raw spectrum.

QoR Metrics to Evaluate

• HB converged at all required corners / drive levels
• p1db_dbm extracted
• Harmonic / spur levels within budget

Common Issues & Fixes

Issue	Fix
HB fails to converge at high drive	retry with more harmonics / source-stepping / continuation (max 2×)
Excess harmonic / spur content	revisit bias/topology — loop back → topology_matching if structural

Output Required

• HB report (p1db_dbm, compression curve, harmonic/spur levels per corner)

---

Stage: noise_linearity

Domain Rules

1. Run Pnoise/PAC (and HB-based two-tone) to extract nf_db (LNA/mixer), iip3_dbm/IIP2, and phase_noise_dbc_hz at the spec offset(s) (VCO/PLL); compute from the tool's noise/spectrum summary.
2. Compare each extracted metric to its rf_specs target; a spec miss is the second loop-back trigger to topology_matching (max 2×).
3. If the noise/linearity limiter traces to an on-chip passive's loss/Q (from design_state.em), do not loop locally — open a fix_request → em-modeling for an automated re-solve.

QoR Metrics to Evaluate

• nf_db ≤ target
• iip3_dbm ≥ target
• phase_noise_dbc_hz ≤ target at the spec offset

Common Issues & Fixes

Issue	Fix
nf_db over target, limiter = inductor Q	open fix_request → em-modeling (higher-Q passive) — no local fix
iip3_dbm / phase-noise miss from the circuit	loop back → topology_matching: re-bias / re-top (max 2×)

Output Required

• Noise + linearity report (nf_db, iip3_dbm, phase_noise_dbc_hz per corner) with limiter attribution

---

Stage: loadpull_optimization

Domain Rules

1. For PA/driver blocks, run load-pull (HB-swept load impedance) to find the load for target pae_pct / p1db_dbm / Pout, and (where in spec) evaluate evm_pct under modulated drive; for non-PA blocks, confirm the optimum source/load and compute evm_pct if specified, else pass through.
2. Confirm the load-pull optimum is realizable with the available (EM-modeled) output match; if it demands a passive beyond Q/SRF, open a fix_request → em-modeling for a re-solve.
3. A pae_pct/evm_pct miss loops back to topology_matching (max 2×).

QoR Metrics to Evaluate

• pae_pct ≥ target and p1db_dbm/Pout ≥ target at the chosen load
• evm_pct ≤ target where specified

Common Issues & Fixes

Issue	Fix
Optimum load needs a passive beyond Q/SRF	open fix_request → em-modeling to re-solve the output passive
pae_pct/evm_pct miss with a realizable load	loop back → topology_matching: re-size the output stage / re-match (max 2×)

Output Required

• Load-pull contours + chosen load; pae_pct / p1db_dbm / Pout / evm_pct table per corner

---

Stage: rf_signoff

Sign-off Pass Criteria (all must pass)

Check	Criterion
Spec compliance	every in-scope rf_specs (nf/gain/s11/iip3/p1db/phase-noise/pae/evm) meets target across the required corners
Stability	k_factor ≥ 1 in-band where unconditional stability is required
Convergence	all S-param/HB/Pnoise analyses converged at every corner
Passive validity	on-chip passives used the EM-fitted model (no ideal substitute at sign-off)

Domain Rules

1. Confirm spec compliance, stability, convergence, and passive validity all pass.
2. Mark the block signed off and publish the RF spec-compliance table + Touchstone/HB/Pnoise reports.
3. Close any serviced re-validation (after a circuit-design rework or em-modeling re-solve) as PASS.

Failure Handling

• Spec/stability fail after the stage-local retry cap → open a cross-domain fix_request (route_to: circuit-design for a device-level miss, or route_to: em-modeling when the limiter is an on-chip passive); terminate with decision: escalate so the pipeline-orchestrator dispatches the servicer and re-validates via this orchestrator.
• Escalate to the user only for a genuine spec_gap (ambiguous/missing spec) or when the cross-domain iteration cap is hit.

Output Required

• RF sign-off report (spec compliance, stability, convergence, passive validity)
• Published S-parameter / HB / Pnoise artifacts

---

Constraint Validation

See plugins/meta/skills/pipeline-orchestration/SKILL.md §Constraints Schema for the authoritative schema and stage-entry validation rule.

Required at entry (rf_spec) — hard-fail if missing:

• constraints.supply.vdd_v — bias / headroom
• at least one non-null entry in constraints.rf_specs (or constraints.specs for a baseband block) — the spec(s) to close
• constraints.pdk — device models / passive layer stack

constraints.corners.process falls back to ["tt"] with a WARN if absent. Skip constraint validation entirely when invoked in re-run / fix-servicing mode (a fix_request.id or a serviced em re-solve reference was passed in the prompt).

---

Memory

Run state (write before first stage, update after each stage)

Write memory/rf/run_state.md as the first action:

run_id:      rf_<YYYYMMDD>_<HHMMSS>
design_name: <design>
pdk:         <pdk or unknown>
tool:        <primary tool>
start_time:  <ISO-8601>
last_stage:  null

Update last_stage to the completed stage name only after each stage finishes successfully.

Write on stage completion

After each stage completes, upsert one JSON record in memory/rf/experiences.jsonl keyed by run_id. key_metrics fields: nf_db, gain_db, iip3_dbm, phase_noise_dbc_hz. Set signoff_achieved: false until rf_signoff passes; then true. Create the file and parent directories if they do not exist.

Optional: claude-mem index

If mcp__plugin_ecc_memory__add_observations is available, emit each matching/stability/HB fix as an observation to entity analog-design-rf-fixes after writing to experiences.jsonl. Skip silently if absent — the JSONL file is the canonical record.