automotive-skills-suite/docs/skill-polish-log/dbc-builder.md

dbc-builder polish log

Polish target for W21 (issue #7). Reviewer: autonomous daily-standup task.

---

2026-05-20 — first POLISH pass (W21 Wednesday)

Mode: POLISH (Wednesday) File reviewed: skills/dbc-builder.skill (ZIP archive; SKILL.md is 6,878 bytes / 115 lines). DoD recap (from docs/weekly/WEEK-2026-W21.md, target #2): description trigger list includes "CAN database," "signal definition," "DBC file," "Vector CANdb," and at least one casual phrasing ("define CAN messages"); description ≤ 1024 chars; frontmatter complete.

DoD verdict

DoD check	Result	Evidence
Trigger phrase "CAN database"	PASS	verbatim twice — "from a CAN database definition" and in the "mentions DBC, CAN database, Vector DBC..." trigger list
Trigger phrase "signal definition"	MARGINAL PASS	present only as a substring of "signal definitions with bit positions" in the descriptive sentence; not in the explicit "mentions ..." trigger list (which carries "signal catalog" instead)
Trigger phrase "DBC file"	FAIL	description carries "DBC" and "Vector DBC" but never the bigram "DBC file"; "DBC file" appears only in the SKILL.md body
Trigger phrase "Vector CANdb"	FAIL	description says "Vector DBC"; Vector's authoring tool / format family is CANdb (CANdb++). The DoD-specified phrase "Vector CANdb" is absent
At least one casual phrasing	PASS	two present — "document our CAN signals" and "audit the message catalog" (the DoD's "define CAN messages" is one example of the class, not a literal requirement)
Description ≤ 1024 chars	PASS	674 chars — generous headroom
Frontmatter complete	PASS	name + description both present; YAML parses; no drift fields

Headline: the W20 pattern (one missing formal trigger phrase per polish target) resumes and doubles — dbc-builder is missing two DoD trigger phrases, not one. Predicted in yesterday's 8d log ("comms cluster hasn't been touched yet so trigger-coverage drift is plausible"); confirmed. Separately, this pass turned up a doc-vs-archive accuracy defect that is more impactful than the trigger gaps (see "What to fix" #3).

What's good

• 11-tab claim is exact and matches the generator. Cross-checked SKILL.md's "11-tab xlsx" + the Output structure table against scripts/generate_dbc.py: the generator emits 00_Title_Page · 01_Document_Control · 02_ECU_Inventory · 03_Message_Catalog · 04_Signal_Catalog · 05_Signal-to-Message_Mapping · 06_Value_Tables · 07_Signal_Group_Definitions · 08_Network_Topology · 09_Validation_Rules · 10_References — 11 create_sheet calls, 00–10. Count, names, and ordering all match the doc. No drift between description, the Output structure table, and code.
• Description char count is generous. 674 / 1024 — ~350 chars of headroom, so the proposed rewrite (adds three trigger phrases + one casual phrasing) lands well under the cap.
• Frontmatter is clean. Both required keys present; YAML parses; no stray fields.
• Body is well-structured. Five-step workflow (Capture → Read refs → Build JSON → Generate → Present/iterate), an explicit "When to use" list, a "Common pitfalls" list, and a "Files in this skill" tree. Among the more complete SKILL.md bodies in the suite — the comms cluster is in good shape structurally.
• Standards anchoring is correct. CAN 2.0A/2.0B, ISO 11898-1:2015, AUTOSAR Communication module all cited accurately; generator's References tab matches.
• JSON-is-source-of-truth guidance is explicit. Step 5 tells the model to edit the input JSON and regenerate rather than hand-editing the xlsx — good operational hygiene, consistent with peer builders.

What to fix

1. "DBC file" absent from the description trigger list. DoD-required phrase. The description has "DBC" and "Vector DBC"; a user who types "generate a DBC file" or "we need a DBC file for this bus" gets only a partial-token match on "DBC". Adding the literal bigram "DBC file" to the "mentions ..." list closes it. Severity: medium (DoD gap, common user phrasing).

2. "Vector CANdb" absent; description says "Vector DBC" instead. DoD-required phrase. "Vector DBC" and "Vector CANdb" are both real — CANdb / CANdb++ is Vector's DBC-authoring product line — but the DoD specifies "Vector CANdb". Best fix keeps both: a user may search either. Severity: medium (DoD gap).

3. SKILL.md "Files in this skill" tree claims examples/sample_input_can.json, but the archive ships NO examples/ directory. Extracted the .skill ZIP and enumerated all 7 files: SKILL.md, references/dbc_conventions.md, references/methodology.md, scripts/generate_dbc.py, scripts/recalc.py, scripts/office/__init__.py, scripts/office/soffice.py. There is no examples/ folder. Yet the SKILL.md tree block lists examples/sample_input_can.json # full example to clone for new projects, and Step 3 of the workflow leans on cloning a worked example. This is a real accuracy defect: a model/engineer following SKILL.md will look for a file that was never packaged. Note the contrast with 8d-problem-solving-builder (yesterday's target), whose archive does ship a populated examples/sample_8d_input.json. Two candidate remedies: (a) author and bundle examples/sample_input_can.json — the generator docstring already documents the schema, so a worked CAN example is straightforward to produce; or (b) drop the examples/ line from the tree and soften Step 3. Remedy (a) is preferred — it brings dbc-builder to parity with the suite norm. Severity: medium (doc references a non-existent shipped artifact).

4. "signal definition" only reaches the description as a substring. It rides inside "signal definitions with bit positions" in the descriptive sentence; the explicit trigger list carries "signal catalog" but not "signal definition". A substring match is weaker than a list entry. Folding "signal definition" into the "mentions ..." list makes the DoD check unambiguous. Severity: low.

5. Casual-phrasing coverage is adequate but misses the canonical verb "define". The two casual phrasings present ("document our CAN signals", "audit the message catalog") are document/audit framed. A very common authoring-intent phrasing — "define CAN messages" / "define the CAN signals" — has no match. The DoD's parenthetical names exactly this phrase. Adding it is cheap and closes a realistic invocation path. Severity: low.

Suggested edits (NOT applied this run)

The autonomous-edit allowlist for the daily-standup task is narrow — typo, over-length description, missing required frontmatter field. None of findings #1–#5 match that list: #1, #2, #4, #5 are editorial trigger-coverage rewrites and #3 is either a content-authoring task (bundle a new example file) or a doc accuracy rewrite. Per the hard rule "stop short of any change you'd need to think hard about," and consistent with the 8d-problem-solving-builder pass on 2026-05-19, no edits were committed to the .skill archive this run. Findings captured here for the next human review pass. Issue #7 stays open with this log linked from the journal entry.

Minimal proposed rewrite of the description — adds "DBC file", "Vector CANdb" (keeping "Vector DBC"), "signal definition", and the casual phrasing "define CAN messages" to the trigger surface; all existing phrases preserved; 741 chars, under the 1024 cap:

description: Generate an audit-ready DBC specification workbook from a CAN database
  definition. Produces an 11-tab xlsx capturing ECU inventory, message catalog with
  IDs and DLC, signal definitions with bit positions/length/byte order/scaling/units/
  value tables, message-signal allocation, network topology, and validation rules per
  CAN 2.0A/2.0B and ISO 11898. Use this skill whenever the user mentions DBC, DBC
  file, CAN database, Vector CANdb, Vector DBC, communication matrix for CAN, message
  catalog, signal catalog, signal definition, or CAN message specification, even in
  casual phrasings like "document our CAN signals", "define CAN messages", or "audit
  the message catalog". Always use this skill instead of producing freeform DBC notes
  in chat.

Check	Result
Char count	741 (under 1024 cap)
"CAN database" in trigger list	yes
"DBC file" in trigger list	yes (added)
"Vector CANdb" in trigger list	yes (added)
"signal definition" in trigger list	yes (added)
Casual phrasing "define CAN messages"	yes (added)
Existing phrases preserved	yes — DBC, Vector DBC, communication matrix for CAN, message catalog, signal catalog, CAN message specification all retained

Finding #3 (the missing examples/ file) is not addressed by the description rewrite — it needs either a new bundled example JSON or a tree-block edit, and is left for human review.

Other observations (not fixes, just notes for future passes)

• The comms cluster (8 builders) all key off this skill's vocabulary — communication-matrix, bus-load, gateway-routing, arxml-system. The examples/ gap (finding #3) is worth a spot-check across the rest of the comms cluster on a future pass: if dbc-builder shipped without its example, sibling comms builders may have the same packaging miss.
• references/dbc_conventions.md mentions J1939 awareness; the description does not. J1939 is a CAN higher-layer protocol with its own large user base. Not a DoD item and arguably out of scope for a generic DBC builder, but a "J1939" trigger token is a plausible future addition if the suite ever wants J1939 reach. Flagged, no action.
• CAN FD: Step 1 of the workflow mentions "CAN FD awareness" in the interview prompts, but neither the description nor the Output structure surfaces CAN FD. If the generator does not actually model CAN FD (64-byte payloads, BRS), the workflow prompt slightly over-promises. Worth a generator spot-check next pass — out of DoD scope today.
• recalc.py and scripts/office/soffice.py are present — the shared helper pair every builder in the suite carries. Consistent.

Severity roll-up

Finding	Severity	Action
"DBC file" absent from trigger list	medium	proposed rewrite drafted; await human review
"Vector CANdb" absent (has "Vector DBC")	medium	folded into the same rewrite
examples/sample_input_can.json claimed but not shipped	medium	needs bundled example or tree edit; left for human
"signal definition" only a substring, not a list entry	low	folded into the rewrite
Casual phrasing "define CAN messages" missing	low	folded into the rewrite

No code edits committed in this run. Issue #7 stays open with this log linked. The W20 trigger-coverage-drift pattern resumed and intensified (two missing DoD phrases vs. one). The standout finding is non-DoD: the SKILL.md "Files in this skill" tree advertises an examples/ file the archive never shipped. Recommendation for the next POLISH (W21 #8 autosar-swc-builder, Thursday): when extracting the archive, explicitly diff the SKILL.md "Files in this skill" tree against the actual ZIP contents — the dbc-builder examples/ miss suggests this drift may be cluster-wide.