Phase 1 — prompt / dialogue entry point
First: IC path or IP path? Read IC Expert § 0.0 before Phase 1. Decide from the prompt or ask the person running it when neither or both routes are stated; record the owner answer with its quotation in input/step_0_5ic_answers.json.
This is one of two entry points to the Vibe-IC platform. See "Two entry points" below for the complete picture.
Phase 1 (this skill): Prompt / Dialogue ──► L1-L27 JSON ──┐
+ Human Readable .md │
▼
Phase 2 → Phase 3
Phase 1 emits the L1-L27 JSON directly — Phase 1 is NOT in this path. The JSON files are the universal handoff format consumed by Phase 2. The Markdown views are for human review only and have no load-bearing downstream consumer.
Two entry points to the platform
| Entry | Skill chain | When to use |
|---|---|---|
| A. Prompt / Dialogue | this phase1 skill (+ spec-review for final confirm) |
User has only an idea, wants AI to author the spec via dialogue |
| B. Existing Design Documents | the unified DOC→JSON track (phase1_doc_one_shot_runner), then phase1-output-verify + phase1-completeness-deep-review |
User already has vendor PDFs / hand-authored markdown spec, wants per-layer extraction |
Both entry points converge at L1-L27 JSON, then enter Phase 2 → Phase 3.
What Phase 1 (this skill) does
- Ingest a prompt (NL) or structured YAML into a
facts.yaml(UUID-tagged, provenance-tracked fact graph) - Detect gaps against the IC class template
- Run the IC Expert Agent dialogue (the merged front-door role asks the user about gaps in its plain-language register)
- The same IC Expert Agent fills residual gaps from K3 industry defaults / class reference / retrieved-neighbour ICs
- Render:
generated_docs/L*.json— the canonical machine-readable form (fed to Phase 2)human_docs/L*.md— Markdown views of the same content (for stakeholder review; added v0.60)
- Emit a per-fact provenance audit (
PROVENANCE.md)
A fact graph is a single source of truth; both the JSON and the Markdown are just views over it.
Layer scope
| Layer | Filename | Phase | Notes |
|---|---|---|---|
| L1 | L1_DATASHEET.json | 1 | core |
| L2 | L2_FRS.json | 1 | core |
| L3 | L3_CMD_PROTOCOL.json | 1 | core; sentinel protocol_present:false legal for memory/analog ICs |
| L4 | L4_REGMAP.json | 1 | core |
| L5 | L5_ADI_SPEC.json | 1 | core |
| L6 | L6_CONTROL_LOGIC.json | 1 | core |
| L7 | L7_TEST_DEBUG.json | 1 | core |
| L8 | L8_TIMING_WAVEFORM.json | 1 | core |
| L8R | L8_RTL_CONSTANTS.json | 1 | core |
| L9 | L9_INTEGRATION_SPEC.json | 1 | core |
| L10 | L10_TEST_CASES.json | 1 | extension — CMD→RSP byte vectors for native simulation |
| L11 | L11_CALIBRATION.json | 1 | extension — platform-specific tuning tables; required domain_clock / source_clock / scale_factor |
| L12 | L12_BEHAVIORAL_SEQUENCES.json | 1 | extension — multi-step protocols (engineer mode unlock, CC reset, etc.) |
| L13 | L13_LAB_CALIBRATION.json | 1+2b | extension — Phase 1 fills the contract (criterion / criterion_params / tester); Phase 2 appends evidence (known_pass_bitstream + known_pass_transcript) |
Why This Supersedes The v0.51 Serial Pipeline
- Dialogue is no longer the input format. Users paste what they have — YAML, tables, OTP hex — and only the remaining gaps go through PM Agent dialogue. Expert users skip dialogue entirely.
- L1..L9 are render views, not authoring steps. No layer can be silently skipped; if a fact needed for L3 is missing, the gap detector surfaces it before rendering.
- Provenance is per-fact, not per-layer. Every fact carries a UUID, source (user_stated / defaulted / retrieved / derived / class_floor / class_required / inferred), origin citation, and trust score. Phase 2/3 failures trace back to offending facts.
- No LLM in render.
facts.yaml → L*.jsonis pure Python. The only LLM calls happen in ingest (parsing free-text user input) and in the optional PM dialogue for unfilled gaps.
Input modes (all land in the same facts.yaml)
| User gives you … | How Phase 1 runs |
|---|---|
| A paragraph in plain language | NL mode — IC Expert Agent (plain-language register) calls nl-ingest, runs gap dialogue, then renders |
A structured spec.yaml |
Fast-path — one run-all call, no dialogue, renders |
| A pin-table CSV (v0.74) | ingest-pins → L1.pinout.* facts (optionally --merge-into an existing facts.yaml) |
| A register-map CSV (v0.74) | ingest-regmap-csv → L4.registers.* facts |
| An OTP hex image — Intel HEX or raw hex (v0.74) | ingest-otp-hex → L4.otp.* facts |
| Existing L1..L9 JSON docs | ingest-docs — reverse-extracts facts |
Both NL and fast-path modes finish at the same output shape
(generated_docs/L1..L9.json + optional L10-L13).
The NL mode preserves the "design a chip in natural language" product promise.
NL-mode extraction is model-neutral (v0.74): the caller must specify
an Anthropic model via --model <id> or the $PHASE1_NL_MODEL env var.
There is no default model — the skill does not prefer any specific one.
Usage
NL mode (common / medium user — "design a chip in natural language")
Invoked by the IC Expert Agent (see ../../agents/ic-expert-agent.md). Minimal end-to-end:
# 1. NL → seed facts (calls Anthropic API if ANTHROPIC_API_KEY set)
python3 -m tools.phase1_engine.cli nl-ingest \
--text "I want to build an ID IC inside a USB-C cable; the handset must be able to tell whether the cable is genuine..." \
--class-path cable-side-id-ic \
--out facts.yaml
# 2. detect gaps
python3 -m tools.phase1_engine.cli gaps facts.yaml --out-json gaps.json
# 3. IC Expert Agent iterates: for each gap, pick K2 qbank variant, ask user, then:
python3 -m tools.phase1_engine.cli set-fact facts.yaml \
--path "L3.frame_format.crc.poly" --value "0x31" --source user_stated
# 4. render when gaps resolved (IC Expert fills residual with defaults)
python3 -m tools.phase1_engine.cli render facts.yaml ./out/generated_docs/ \
--provenance-report ./out/PROVENANCE.md
If ANTHROPIC_API_KEY is not set, nl-ingest --prompt-only emits the
extraction prompt so a calling agent can run the LLM externally, then
feed facts JSON back via ingest-extracted.
Fast-path (expert: structured YAML)
python3 -m tools.phase1_engine.cli run-all path/to/spec.yaml ./out
spec.yaml format:
ic_name: MY_IC
class_path: cable-side-id-ic
L1:
ic_name: MY_IC
pinout: { VBUS: "Pin 1 — ...", ... }
electrical_characteristics: { supply_vbus: { min: 4.5, typ: 5.0, max: 5.5, unit: V } }
...
L3:
protocol_name: ...
commands: [ { opcode: "0x70", name: CMD_PING, ... } ]
...
Output:
out/
├── facts.yaml # fact graph (YAML)
├── gaps.json # gap report
├── PROVENANCE.md # per-fact audit trail
└── generated_docs/
├── L1_DATASHEET.json
├── L2_FRS.json
├── ...
└── L9_INTEGRATION_SPEC.json
From existing docs (regression / refactor)
python3 -m tools.phase1_engine.cli ingest-docs path/to/generated_docs/ --out facts.yaml
python3 -m tools.phase1_engine.cli render facts.yaml ./out/generated_docs/ --provenance-report ./out/PROVENANCE.md
Phase 1 layers and where each one is authored
These are LAYERS, not skills. An earlier revision of this file listed
seventeen per-layer skill names here (datasheet-gen … otp-content-gen)
and marked them "restored to active in v0.60". NONE of the seventeen exists
under skills/ — ls skills/ returns no such directory for any of them, and
the canonical flow's step D1 named all seventeen too until that was corrected
in the same change as this paragraph. An agent told to invoke one cannot, so it
hand-authors instead; that is exactly the failure v1.12.76 measured for
testbench-author, where the hand-authored artefact missed a contract the step
hard-FAILs on. The names are recorded under unbuilt_skills in
skills/_classification.json so they cannot quietly return.
Every layer below is authored by the unified DOC→JSON track
(phase1_doc_one_shot_runner / the tools.phase1_engine render pipeline
shown above), which reads the whole document set at once. Per-layer
re-rendering is a re-run of that track, not a separate skill invocation.
| Layer | Document |
|---|---|
| L1 | L1_DATASHEET.json |
| L2 | L2_FRS.json |
| L3 | L3_CMD_PROTOCOL.json |
| L4 | L4_REGMAP.json (OTP .ver image emitted when L4 declares OTP) |
| L5 | L5_ADI_SPEC.json |
| L6 | L6_CONTROL_LOGIC.json |
| L7 | L7_TEST_DEBUG.json |
| L8 | L8_TIMING_WAVEFORM.json |
| L8R | L8_RTL_CONSTANTS.json |
| L9 | L9_INTEGRATION_SPEC.json (+ the derived block diagram) |
| L10 | L10_TEST_CASES.json |
| L11 | L11_CALIBRATION.json |
| L12 | L12_BEHAVIORAL_SEQUENCES.json |
| L13 | L13_LAB_CALIBRATION.json |
| cross-layer | AI review each admitted fact at its real consumer field against the provided source; read native results in reports/flow_engine.json against original requirements and disclose NOT_MEASURED where evidence is absent |
When the input affirmatively requires paired or round-trip verification, author round_trip: true in L10 with the cited input sentence as round_trip_source.
A prohibition, an optional mention, or background text is not a requirement; the Program only consumes the typed field and never infers it from wording.
When the input requires the GCM procedure, author gcm_round_trip: true with gcm_procedure_evidence citing the supplied procedure; do not promote capability documentation into required verification.
The skills that DO ship for this stage are this phase1 skill and the two
verification-tier reviewers phase1-output-verify and
phase1-completeness-deep-review. Step D1 of the canonical flow declares
phase1; the two reviewers are on-pass reviewers and belong in a stage-level
on_pass_review: block (the field v1.12.87 added for exactly that role), not
in the step's skills: list, whose meaning at every site is "invoke this when
the step could not, or when the step failed".
The v0.51 prompt-intake and phase1-orchestrate skills are NOT
restored — their function is fully subsumed by this phase1 skill's
ingest + IC Expert Agent dialogue + render pipeline. They remain archived at
legacy/skills_phase1_v051/ for reference.
Dialogue-driven (common / medium user)
The IC Expert Agent (see ../../agents/ic-expert-agent.md) drives an
interactive session in its plain-language register,
calling tools/phase1_engine/cli.py internally:
prompt-intakegathers initial free-text.- Whatever facts can be parsed from the text become the seed fact graph.
gapsreports remaining required-but-missing facts.- IC Expert Agent asks the user about each gap in its plain-language register (using the Q-bank, K2).
- Unanswered gaps → IC Expert fills from K3 / class_reference / retrieved
neighbour with
source=defaultedorsource=retrieved. renderemits the 14 layer JSONs — 10 core (L1-L9 + L8R) plus 4 extension (L10-L13). The extension layers are skipped silently when no facts under their prefix exist (e.g. an IC with no L12 sequences simply doesn't get anL12_BEHAVIORAL_SEQUENCES.json).
Review the generated documents
Read the current document-generation row and its native producer output. Compare the input documents with the owning generated fields. Check layer coverage, cross-layer consistency, units, clock scales, register and opcode semantics, and explicit absent-feature declarations. A missing requirement stays open until its producer carries it to the correct consumer.
Use the selected row's original requirements. Do not replace source review with a schema, receipt, persona-quality score or fixed document count.
Agents
ONE agent operates in two registers on the fact graph (not on layer docs):
- External register translates user intent into fact-level updates (one fact per dialogue turn). Never asks a technical question the user cannot answer at their level — plain product language only, no silicon jargon.
- Internal register reviews the fact graph for consistency, fills gaps from K3 / retrieved neighbours, flags high-impact conflicts for user confirmation (surfaced back through the external register).
See ../../agents/ic-expert-agent.md.
Where Things Live
| What | Where |
|---|---|
| Fact-graph schema + dataclasses | tools/phase1_engine/schema.py |
| Ingesters (docs, YAML, bulk paste) | tools/phase1_engine/ingest.py |
| Gap detector | tools/phase1_engine/gap_detect.py |
| Renderer (JSON + Markdown) | tools/phase1_engine/render.py (render_layers + render_human_docs) |
| Retrieval (top-K similar ICs) | tools/phase1_engine/retrieve.py |
| CLI | tools/phase1_engine/cli.py (run-all / render --human-docs-dir) |
| Class templates (K1) | vibe-ic/agents/class_kb/templates/ |
| Q-bank (K2) | vibe-ic/agents/qbank/ |
| Defaults (K3) | vibe-ic/agents/defaults/ |
| Consistency rules (K4) | Source facts and their owning generated fields |
| Runtime feedback (K5) | Measured downstream failures and extractor regression cases |
Legacy
The v0.51 prompt-intake and phase1-orchestrate skills are archived
at legacy/skills_phase1_v051/ and are no longer invoked — their
function is subsumed by this phase1 skill.
The 10 v0.51 doc-gen skills (datasheet-gen through integration-spec-gen)
were archived in v0.58. This file used to claim they were "restored to active
in v0.60"; they were not, and none of them ships. Entry B
(existing-Design-Documents → L1-L27) is served by the unified DOC→JSON track.
See "Phase 1 layers and where each one is authored" above.