| name | ip-design |
| description | Guide for RTL/IP design — new designs from scratch, existing-RTL documentation, or existing-doc implementation. Covers spec-first workflow, user confirmation gates, project structure, RTL/filelist/testbench/testcase/SDC synchronization. Use when user asks to design new IP, write docs for existing RTL, implement RTL from existing docs, add testbenches, or any combination of RTL design deliverables. |
IP Design Skill (RTL)
Use this skill for any RTL/IP design task. Three entry points, one unified flow.
Core Principles
- Plan-first: Enter plan mode, enumerate steps, execute step-by-step.
- Spec-first: Always produce a spec.md to our standard → Review → User confirms → Then downstream work.
- Synchronize downstream: Any requirement/RTL change triggers updates to filelist, TB, testcases, SDC.
- Pure RTL: Synthesizable Verilog/SystemVerilog. No macros. Plain and portable.
- Honest status: Never mark a task complete when it is blocked or unverified. See
reference/status_template.md.
- Language consistency: All docs follow user's communication language.
- Transparent consensus: Never secretly change confirmed approach. See
reference/consensus_rules.md.
- Atomic doc updates: Text + diagrams + structure = the specification. Update all together. See
reference/change_management.md.
Workflow Overview
Step 0: Determine entry point + deliverables + design targets
→ Step 1: Project structure
→ Step 2: Write spec.md + testplan.md (source depends on entry point)
→ Step 3: Spec & testplan review
→ ⛔ GATE: User confirms spec + testplan + drawio
→ Step 4: RTL ← user selectable
→ Step 5: RTL review ← if Step 4 runs or RTL exists
→ Step 5b: Logic depth analysis (fast_elab) ← if RTL exists
→ Step 6: TB + smoke ← user selectable
→ Step 7: All tests ← user selectable
→ Step 8: SDC ← user selectable
→ Step 9: Makefile ← user selectable
→ Step 10: Coverage ← user selectable
Steps 0–3 and GATE are always executed. Steps 4–10 are user-selectable deliverables.
Blocking rules (always enforced on active steps):
- Unconfirmed spec + testplan → no downstream work.
- Missing drawio diagram → GATE cannot proceed.
- Unreviewed RTL → no TB.
- Failed or never-run compilation → Step 6 is NOT complete.
- Any failed test → Step 7 is NOT complete.
Workflow
Step 0: Entry Point & Deliverables
0a. Determine entry point from user's request.
| User says (examples) | Entry | Spec source |
|---|
| "设计一个 XX" / "从零开始" / "design a new XX" | NEW | Write from requirements |
| "我有 RTL" / "已有代码" / "I have existing RTL" | HAS_RTL | Extract from RTL, see reference/rtl2doc_guide.md |
| "我有文档" / "已有 spec" / "I have a design doc" | HAS_DOC | Rewrite from existing doc, see reference/doc2doc_guide.md |
⚠️ The user decides the entry point. Never auto-detect from filesystem.
If unclear, ask once: "请问您的起点是什么？（从零设计 / 已有 RTL / 已有文档）"
If HAS_RTL but no RTL files found, ask: "请提供 RTL 文件路径，或放入 <project>/rtl/。"
If HAS_DOC but no doc found, ask: "请提供现有文档路径。"
0b. Determine deliverables.
After GATE, the default deliverables depend on entry:
| Entry | Default deliverables after GATE | User can override? |
|---|
| NEW | RTL → Review → TB → Tests → SDC → Makefile (all) | Can remove any |
| HAS_RTL | Review → TB → Tests → SDC → Makefile (skip RTL) | Can add RTL rewrite, can remove any |
| HAS_DOC | RTL → Review → TB → Tests → SDC → Makefile (all) | Can remove any |
Ask user: "GATE 通过后，您需要以下哪些交付物？（默认：[列出默认项]）"
Or user may specify upfront: "只要文档" / "文档和TB" / "全部" — respect their choice.
Record entry point and selected deliverables in status.md.
0c. Determine design targets.
Ask the user for the following two design targets (translate to user's language):
请确认以下设计目标：
1️⃣ 目标覆盖率是多少？（常见选项：90% / 95% / 100%，默认 95%）
2️⃣ 可接受的最大组合逻辑级数（gate levels）是多少？（常见选项：10 / 15 / 20 级，默认 15）
— 组合逻辑级数影响最高可达频率，级数越少频率越高。
If user doesn't specify, use defaults: coverage 95%, max logic depth 15 levels.
Record in status.md:
## Design Targets
- Target coverage: <user_value>%
- Max combinational logic depth: <user_value> gate levels
These targets will be used in:
- Step 5b:
fast_elab logic depth analysis and optimization
- Step 10: Coverage closure target
DONE CRITERIA: Entry point, deliverables, and design targets determined. Proceed to Step 1.
Step 1: Project Structure
Create folder layout:
<project>/
status.md ← from reference/status_template.md
docs/
spec.md ← design specification (no verification plan)
testplan.md ← verification plan (testcase list + pass criteria)
*_arch.drawio ← editable diagram source
*_arch.png ← exported real PNG (not ASCII text)
rtl/
tb/ ← infrastructure ONLY (no test stimulus)
testcase/ ← each test in separate file (tc001_*.sv, tc002_*.sv)
work/ ← gitignored simulation artifacts
filelist/
rtl.f
tb.f
constraint/
design.sdc
DONE CRITERIA: All directories exist. status.md created from template. Proceed to Step 2.
Step 2: Write spec.md + testplan.md
This step always runs. The spec must conform to our standard regardless of entry point.
Information source by entry:
| Entry | Action |
|---|
| NEW | Write spec from user requirements. Propose defaults for unspecified parameters. |
| HAS_RTL | Read reference/rtl2doc_guide.md. Systematically extract from RTL. Do NOT invent behavior — document what RTL actually does. If information is missing from RTL (e.g., clock frequency), ask user. |
| HAS_DOC | Read reference/doc2doc_guide.md. Rewrite existing doc into our standard format. Preserve all information. If existing doc has gaps, flag them and ask user to fill. |
spec.md must include (all entries):
- Clock definition table (name, frequency, period, domain)
- Reset definition (name, polarity, sync/async, domain)
- I/O definition table (signal, direction, width, clock/reset)
- Parameter table (name, default, valid range, derived values)
- Feature list with edge case behavior
- Module hierarchy tree + microarchitecture diagram (see
reference/microarch_diagram_guidelines.md)
- Create
docs/*_arch.drawio → export PNG using VS Code drawio extension (see §7.2 of diagram guidelines) → embed  in spec
- If drawio export tool unavailable → report to user, do NOT silently skip PNG
- Design constraints summary (clock frequencies, CDC, reset)
spec.md must NOT include: verification plan / testcase list. Those go in testplan.md.
testplan.md must include (see reference/testplan_guide.md for full format):
- Testbench architecture overview (block diagram, scoreboard strategy)
- Testcase list table: 编号 (tc001, tc002...), 名称, 激励描述, 通过标准
- Testcase naming rule: 编号 = testcase 文件名前缀（e.g., tc001 →
testcase/tc001_*.sv），不可有别名
- Parameter test matrix (which configs × which testcases)
- Coverage targets
- TB timing/scheduling rules (driver timing, monitor sampling, cross-clock considerations)
Consistency verification (mandatory after writing):
- Extract module names from: text spec, diagram, deliverables list
- All three lists must match exactly
- For HAS_RTL / HAS_DOC: cross-check spec against source material — no info loss
- If mismatch → fix ALL before proceeding
Annotation rules (apply to ALL project files written after this point):
- File header: ≤ 10 lines
- Inline comments: only for non-obvious design decisions
- Prohibited: textbook explanations, repeating spec content in code
- Target ratio: code ≥ 60%, comments ≤ 40%
DONE CRITERIA: spec.md has all required sections. testplan.md has testcase list with automatable pass criteria. Testcase naming matches filename convention. Diagram is real PNG matching text. Proceed to Step 3.
Step 3: Spec & Testplan Review — MANDATORY
This review MUST happen. Choose one option based on tool availability:
Option A — Sub-agent (preferred):
Invoke runSubagent with description "Spec and testplan review" and this prompt:
You are an independent spec reviewer. Execute these steps:
1. Read file: skills/skills/ip-design/reference/doc_review_checklist.md
2. Read file: skills/skills/ip-design/reference/testplan_guide.md
3. Read file: <project_path>/docs/spec.md
4. Read file: <project_path>/docs/testplan.md
5. Evaluate spec against ALL 7 checklist categories:
Completeness, Internal Consistency, Clarity, Parameter Spec,
Design Justification, Formatting, Diagram Quality
6. Evaluate testplan against testplan_guide.md:
- Testcase naming: 编号 must equal filename prefix (tc001 → tc001_*.sv)
- Each testcase has specific stimulus description and automatable pass criteria
- TB timing rules are specified (driver/monitor scheduling)
- Coverage targets defined
7. Cross-check: spec module list matches testplan DUT references
8. For each category: Status (✅/⚠️/❌) + Finding + Suggested Fix
9. Return structured report with:
- Verdict: ✅ READY / ⚠️ NEEDS IMPROVEMENT / ❌ MAJOR GAPS
- Issues table: # | Severity 🔴/🟡/🔵 | Category | Issue | Fix
HAS_RTL addition: After standard review, cross-check spec against RTL using Phase 3 of reference/rtl2doc_guide.md.
HAS_DOC addition: After standard review, cross-check spec against original doc — verify no information was lost during rewrite.
Option B — Self-review fallback: Same checklist, record in status.md, note "Self-review mode".
⚠️ User pre-authorization does NOT skip review. Review is an internal quality gate, independent of user confirmation. Even if user said "不用问我", execute review normally.
Self-review minimum recording: If using Option B, status.md must include at least:
- Each of the 7 checklist categories explicitly listed with ✅/⚠️/❌ verdict
- At least one specific judgment per category (not just "OK")
- A bare "READY" or "CLEAN" without per-category detail is NOT acceptable
After review: Fix all ⚠️ and ❌ issues. Proceed to GATE.
DONE CRITERIA: Review report in status.md with per-category detail. All issues resolved.
⛔ GATE: User Confirmation — RIGID PROTOCOL
G-1. Pre-authorization check:
If user explicitly stated upfront that spec is pre-approved (e.g., "你输出的SPEC我确认",
"skip review", "直接做", "不用问我"), treat as valid pre-authorization:
- Still execute Steps 2–3 (spec writing + review) normally — quality gates are internal, not user-facing
- At GATE, skip G2 (don't send confirmation request)
- Record in status.md:
## ⛔ GATE: PASSED — User pre-authorized on <date>
- Include the user's exact pre-authorization statement as evidence
- Proceed directly to selected deliverables
G0. Pre-GATE mandatory checklist — verify before presenting to user:
G1. Write in status.md: ## ⛔ GATE: AWAITING USER CONFIRMATION
G2. Send this message (translate to user's language):
✅ spec.md + testplan.md 已完成并经过内部评审。
📋 请审阅：
- docs/spec.md — 特别注意：[列出 3-5 个关键参数]
- docs/testplan.md — 测试用例列表与通过标准
- docs/*_arch.drawio / .png — 微架构图
⏸️ 等待您的确认。请回复"确认"或提出修改意见。
⚠️ 在您明确确认之前，我不会开始任何下游工作。
📦 确认后将执行：[列出已选定的交付物]
G3. Check for explicit confirmation:
- ✅ Valid: "确认" / "没问题" / "可以" / "同意" / "通过" / "好的" / "confirmed" / "OK" / "yes"
- ❌ Invalid: "继续" / "你继续" alone → Reply: "我需要您对 spec 的明确确认。请回复'确认'。"
G4. After confirmed: write ## ⛔ GATE: PASSED — User confirmed on <date> in status.md.
G5. Proceed to selected deliverables.
Step 4: RTL + Filelist
Runs when: User selected RTL as deliverable (default for NEW, HAS_DOC; default skip for HAS_RTL unless user requests rewrite).
If HAS_RTL and not rewriting: Only create filelist/rtl.f if missing, then skip to Step 5.
Create synthesizable RTL. Update filelist/rtl.f (dependency order: leaves first).
Coding rules:
- File header ≤ 10 lines
- No textbook explanations in comments
output wire for combinational; output reg only when driven by always block- Active
(* ASYNC_REG = "TRUE" *) on synchronizer registers — never commented out
- No
assign driving an output reg
- Async FIFO full/empty: compare in Gray code domain only (Cummings method)
DONE CRITERIA: All RTL files created. filelist/rtl.f in dependency order.
Step 5: RTL Code Review — MANDATORY (when RTL exists)
Runs when: Step 4 was executed, OR entry is HAS_RTL (review existing code).
Invoke runSubagent (or self-review) with reference/rtl_review_checklist.md. Check all 7 categories: Synthesizability, CDC, Timing, Area, Functional Correctness, Verifiability, Spec Compliance.
⚠️ Self-review minimum recording: If not using sub-agent, status.md must list all 7 categories with explicit ✅/⚠️/❌ verdict and at least one specific finding per category. A bare "CLEAN" is NOT acceptable.
After review: Fix all 🔴 items. If bugs suggest spec misunderstanding → return to user.
DONE CRITERIA: Review report in status.md. All 🔴 items fixed.
Step 5b: Logic Depth Analysis — fast_elab (when RTL exists)
Runs when: Step 5 completed (RTL exists and reviewed). Automatically runs if user specified max logic depth target in Step 0c.
Purpose: Use fast_elab (consult fast-elaborator skill) to analyze combinational logic depth. If any path exceeds the user's target, attempt optimization. If optimization cannot meet the target, prioritize functional correctness and report the achievable minimum.
5b-1. Load design into fast_elab
fast_elab load filelist/rtl.f --top <top_module> --json
5b-2. Analyze logic depth
fast_elab timing --max-paths 10 --json
Extract the worst-case logic depth from the report. Compare against user's target (from Step 0c).
5b-3. Classification
| Worst-case depth vs target | Action |
|---|
| depth ≤ target | ✅ PASS — record in status.md, proceed |
| depth > target | Enter optimization loop (5b-4) |
5b-4. Optimization loop (max 3 iterations)
For each violating path:
fast_elab timing --from <startpoint> --to <endpoint> --json — get gate-by-gate breakdown- Identify the deepest combinational cone — use
fast_elab navigate and fast_elab stat to locate the module
- Apply RTL optimizations (in priority order):
- Pipeline insertion: add register stage to split the critical path
- Logic restructuring: refactor wide MUX/decoder/priority logic into balanced tree
- Pre-computation: move partial results to earlier pipeline stage
- After each RTL change → re-run
fast_elab load + fast_elab timing to verify improvement
- After each RTL change → re-run Step 5 review items affected (Functional Correctness, Spec Compliance)
⚠️ Function-first principle: If an optimization would:
- Break functional correctness (testcases fail)
- Violate spec requirements
- Require spec changes the user hasn't approved
→ STOP optimizing. Revert the change. Keep the functional version.
5b-5. If target cannot be met
After 3 optimization iterations, if logic depth still exceeds the user's target:
- Run final
fast_elab timing --max-paths 10 --json to get the actual minimum achievable depth
- Report to the user (translate to user's language):
⚠️ 组合逻辑级数优化结果：
- 您的目标：≤ <target> 级
- 当前最优：<actual> 级（路径：<from> → <to>）
- 已尝试优化 <N> 轮，进一步优化会影响功能正确性。
- 📌 优先保证功能正确，当前设计的最大组合逻辑级数为 <actual> 级。
- 如需进一步降低，可能需要：
(a) 架构级重构（增加流水级数，需修改 spec）
(b) 放宽时序目标
请确认是否接受当前结果，或需要调整设计方案。
- Wait for user's decision:
- User accepts → record actual depth in status.md, proceed
- User requests spec change → return to Step 2 for spec update → re-run GATE
5b-6. Cleanup
fast_elab close
DONE CRITERIA: Logic depth ≤ target (or user accepted actual achievable depth). Result recorded in status.md. fast_elab daemon closed.
Step 6: Testbench + Smoke Test — MUST COMPILE AND RUN
Runs when: User selected TB as deliverable.
Read reference/testbench_architecture.md for code templates.
Key rules:
- tb/ = infrastructure only. testcase/ = stimulus only.
- ❌ NEVER use
import module_name::* — module is not a package.
- Use hierarchical references or include-based pattern.
- Cross-clock shared resources: separate queues per domain.
Compilation protocol:
C1. Detect: which vcs / which iverilog
C2. Neither → ⏸️ BLOCKED, tell user. DO NOT mark COMPLETED.
C3. Compile → 0 errors required.
C4. Run smoke → grep "PASSED" required.
C5. Record in status.md.
⚠️ On compile/link/runtime errors:
- If the error is not an RTL logic bug (e.g., toolchain, linker, environment, license) → consult
eda_toolchain_debug skill first before guessing fixes.
- If the same command works interactively but fails in scripts → suspect environment differences (aliases, PATH, shell mode), not the command itself.
- After 3 failed fix attempts → stop and re-analyze root cause.
Scoreboard debugging: If simulation passes but scoreboard reports data mismatches, check the sampling-timing rules in reference/testbench_architecture.md — combinational vs registered output requires different monitor timing.
DONE CRITERIA: Compile 0 errors. Smoke PASSED. Evidence in status.md.
Step 7: All Testcases — MUST EXECUTE EACH ONE
Runs when: User selected tests as deliverable (requires Step 6).
Implement all testcases from docs/testplan.md. Each in separate file. Filename must match testplan 编号: tc001 → testcase/tc001_*.sv.
For each: compile → run → verify PASSED → record in status.md. Debug failures.
⚠️ On compile/runtime failure: Same as Step 6 — non-RTL errors go to eda_toolchain_debug first. Simulator-specific syntax limitations should use alternative implementations.
DONE CRITERIA: All testcases PASSED. If any not executed → NOT complete.
Step 8: SDC Constraints
Runs when: User selected SDC as deliverable.
Create constraint/design.sdc consistent with spec. Include: clock defs, async groups, CDC constraints, I/O delays, reset false paths, clock uncertainty.
Consistency rule: set_clock_groups -asynchronous and set_max_delay on same path pair are mutually exclusive.
DONE CRITERIA: SDC exists. Frequencies match spec. No contradictions.
Step 9: Makefile
Runs when: User selected Makefile as deliverable (requires Step 6).
Read reference/makefile_template.md before writing Makefile.
Create tb/Makefile. Targets: compile_<tc>, run_<tc>, regression, clean. Parameterize: SIM ?= vcs.
⚠️ Regression scripts vs interactive terminals:
- Commands that work in interactive terminals may fail in scripts due to environment differences (aliases, env vars, shell mode). On regression failure, consult
eda_toolchain_debug for known cases.
- Makefile/scripts should be self-contained — never rely on user shell aliases or implicit environment setup.
DONE CRITERIA: make regression succeeds.
Step 10: Coverage Closure
Runs when: User selected coverage as deliverable, or asks for coverage analysis after all testcases pass.
Pre-requisite: Step 7 (all testcases PASSED) and Step 9 (Makefile exists).
Read reference/coverage_closure.md before starting. It contains DUT-only strategy, coverage types, waiver best practices, VCS flags, and industry-standard targets.
10a. Add coverage flags to Makefile
- Add
COV ?= 0 flag to Makefile; conditionally add -cm line+tgl+branch+cond+fsm when COV=1
- Add
cm_hier.cfg to collect DUT-only coverage (exclude TB/TC at collection time)
- ⚠️ Some older VCS versions have linker issues with
-cm — consult eda_toolchain_debug (see issues/vcs/003)
- Use
-cm_dir <shared_dir> so all testcases auto-merge into a single VDB
10b. Run coverage regression
make cov_regression (clean → compile with COV=1 → run all TCs → coverage data in VDB)- Verify all TCs still PASS with coverage flags enabled
10c. Analyze with cov-reader (consult cov-reader skill)
- Prefer direct VDB read:
cov_reader open work/cov_merge.vdb — do NOT convert to UCIS XML
- Follow summary-first strategy:
cov_reader summary → identify lowest-coverage types → drill down
- Navigate to DUT scope:
cov_reader navigate <tb_top>.u_dut
10d. Classify coverage holes
- DUT holes → fix with new targeted testcases (see
reference/coverage_closure.md §8 for strategies)
- TB/TC infrastructure holes → waiver (scope-level)
- DFT/debug/reserved in DUT → waiver with documented reason
- If DUT submodules already at 100% → all remaining holes are infrastructure → waiver only
10e. Write waivers (consult cov-reader skill for .cwv.yaml format)
- Use scope-level waivers (no
items) for entire TB/TC module exclusion — most reliable
- Per-item waivers (
{line: N, arm: M}) may silently fail on some DB formats — avoid for bulk exclusion
- Every waiver must have a
reason explaining why it's not testable
- Validate with
validate_waiver() before applying
- Always compare before/after
get_summary() to confirm waivers took effect
10f. Process — incremental closure loop
while coverage < target:
1. Identify highest-impact uncovered area
2. Write 1-2 targeted testcases
3. Re-run cov_regression → check incremental gain
4. If a hole is untestable after 3 attempts → waiver
10g. Verify and report
- Run
get_summary() with waivers loaded → all types ≥ target%
- Generate coverage report (summary + waiver list + uncovered justifications)
DONE CRITERIA: All coverage types ≥ target% (effective, after waivers). Coverage report exists. Waiver file (.cwv.yaml) committed.
Plan Mode Checklist
- [ ] [Step 0] Entry point + deliverables + targets ← ALWAYS
- [ ] [Step 1] Project structure + status.md ← ALWAYS
- [ ] [Step 2] spec.md + testplan.md ← ALWAYS
- [ ] [Step 3] Spec & testplan review ← ALWAYS
- [ ] [GATE] User confirms spec + testplan + drawio← ALWAYS, BLOCKING
- [ ] [Step 4] RTL + rtl.f ← if selected
- [ ] [Step 5] RTL review ← if RTL exists (new or existing)
- [ ] [Step 5b] Logic depth analysis (fast_elab) ← if RTL exists + depth target set
- [ ] [Step 6] TB + smoke test ← if selected
- [ ] [Step 7] All testcases ← if selected
- [ ] [Step 8] SDC ← if selected
- [ ] [Step 9] Makefile + regression ← if selected
- [ ] [Step 10] Coverage closure ← if selected
Reference Documents
| Document | Path | When to Read |
|---|
| RTL-to-doc guide | reference/rtl2doc_guide.md | Step 2 when HAS_RTL — extract spec from code |
| Doc-to-doc guide | reference/doc2doc_guide.md | Step 2 when HAS_DOC — rewrite existing doc to standard |
| Doc review checklist | reference/doc_review_checklist.md | Step 3 — spec review criteria |
| Testplan guide | reference/testplan_guide.md | Step 2/3 — testplan format, naming rules, TB timing |
| RTL review checklist | reference/rtl_review_checklist.md | Step 5 — code review criteria |
| TB architecture | reference/testbench_architecture.md | Step 6/7 — code templates |
| VCS simulation | reference/vcs_sim.md | Step 6/7 — compilation and debugging |
| Diagram guidelines | reference/microarch_diagram_guidelines.md | Step 2 — architecture diagram standards |
| Diagram examples | reference/microarch_examples.md | Step 2 — correct/incorrect comparisons |
| Consensus rules | reference/consensus_rules.md | All steps — stop-and-discuss protocol |
| Change management | reference/change_management.md | Any change — atomic update rules |
| Status template | reference/status_template.md | Step 1 — initial status.md content |
| Makefile template | reference/makefile_template.md | Step 9 — Makefile structure and pitfalls |
| Coverage closure | reference/coverage_closure.md | Step 10 — DUT-only strategy, coverage types, waiver practices, VCS flags |
Related Skills
| Skill | When to Jump | What to Do |
|---|
eda_toolchain_debug | Non-RTL errors in Step 6/7/9 (toolchain, linker, environment, license) | Read its SKILL.md → search issues/ with error keywords |
eda_toolchain_debug | Same command works interactively but fails in scripts/Makefile/CI | Check for environment difference cases |
cov-reader | Step 10 — coverage analysis, hole identification, waiver application | Read its SKILL.md for CLI commands and Python API |
fast-elaborator | Step 5b — logic depth analysis, combinational path optimization | Run fast_elab load → timing → optimize → close |
theme-factory | Need unified theme for docs/diagrams | Read SKILL.md to select theme |
