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

tara-builder polish log

Polish target for W23 (issue #16). Reviewer: autonomous daily-standup task.

---

2026-06-03 — first POLISH pass

Mode: POLISH (Wednesday) File reviewed: skills/tara-builder.skill (ZIP archive; SKILL.md is 12,279 bytes / 150 lines). DoD recap (from docs/weekly/WEEK-2026-W23.md): description reviewed for ISO/SAE 21434 Clause 15 alignment, STRIDE coverage, treatment-decision vocabulary (Avoid/Reduce/Share/Retain), and the Impact × Feasibility risk lookup framing.

What's good

• Frontmatter is clean. Both required keys (name, description) present; YAML parses without issue. Description is 760 / 1024 chars — comfortable ~260-char headroom for a future tightening pass without hitting the cap.
• Clause anchor is explicit and correct. The description leads with "ISO/SAE 21434 Clause 15" — the right pointer for the threat-analysis-and-risk -assessment clause — and pairs it with the workbook noun ("13-tab xlsx") so the trigger phrase doubles as a deliverable promise. Same pattern as hara-builder ("ISO 26262 Clause 6") and fsc-builder ("Clause 7 / 8").
• STRIDE vocabulary is canonically named. Section 2 references the six STRIDE pillars (Spoofing, Tampering, Repudiation, Info Disclosure, Denial of Service, Elevation of Privilege) inside the threat-taxonomy bullet, and the reference doc (stride_taxonomy.md) is wired into the workflow at Step 2. Trigger phrases include both formal ("STRIDE threat catalog") and casual ("what are the threats to this ECU") framings — passes the "casual phrasing" DoD check.
• Treatment vocabulary is consistent. "Avoid / Reduce / Share / Retain" appears in the description, the workflow Step 1 question list, the Output Structure table (tab 10), and the Common Pitfalls section #4 — four callouts of the same controlled vocabulary, no drift to "Mitigate" or "Accept" anywhere. Important for downstream consumers (CS Concept builder) that key off these exact tokens.
• CAL framing is right. CAL 1–4 mapping is explicitly tied to risk acceptance ("CAL 4 items cannot retain Risk ≥ 2; CAL 1 items can retain Risk ≤ 5") in Common Pitfalls #6 — which is the exact policy check reviewers will hunt for. Saves the analyst from defending the rule in the audit room.
• Pipeline hand-off is explicit. Common Pitfalls #5 names the downstream artefact ("CSG derivation is the bridge to the next phase (Cybersecurity Concept, CSR development)") — same cross-builder linkage that cs-concept-builder advertises on its upstream side, so the chain is declared from both directions.
• Output Structure table is complete and well-formed. 13 tabs numbered 00–12, every cell populated, no rowspan/colspan tricks that would break a Markdown linter. Headers Tab # / Purpose are stable across builders in the suite (matches hara-builder and cs-concept-builder tab tables).

What to fix

• Severity: medium — internal contradiction in "Auto-rating Heuristics". The section opens with: "TARA auto-rating is limited. The skill requires user-supplied Impact and Feasibility ratings in the JSON; it does NOT auto-suggest." Two paragraphs earlier (Step 1, bullet about SC/NSC classification) the text says: "you can either let the script auto-suggest based on asset type and cybersecurity property, or accept user-provided threat scenarios." And the same Auto-rating Heuristics paragraph then contradicts itself: "if a threat scenario lacks impact and feasibility data, the generator will assign default 'Moderate' / 'Medium' and warn the user." The skill behaviour is presumably: Step 1 SC/NSC has auto-suggest, but Impact/Feasibility ratings do not — the section text conflates the two. Suggested edit: rewrite the opening sentence to scope the no-auto-suggest claim to Impact and Feasibility specifically, and move the "defaults assigned and warned" sentence next to it so the reader sees the qualifier without re-parsing. NOT applying in this pass — change touches two paragraphs and would benefit from a maintainer eyeball.
• Severity: low — Step 4 shell block is shell-only. The python scripts/generate_tara.py <input.json> <output.xlsx> block has no Windows-equivalent note. Other builders in the suite (cs-concept, dfmea) include a # Windows: python.exe ... parenthetical for cross-platform users. Add one for consistency.
• Severity: low — Step 5 review checklist conflates "high-Risk" vs "Risk ≥ 3". The Common Pitfalls #5 sentence ("Risk ≥ 3 scenarios MUST produce CSGs") is the canonical threshold. Step 5's Cybersecurity Goals tab bullet says: "does each Risk ≥ 3 scenario produce a well-formed CSG ('Prevent ')?" — consistent. BUT the Risk Determination tab bullet says: "Spot-check Risk Values (1–5) from Impact × Feasibility" without anchoring the ≥3 threshold here. Add a one-line "Anything ≥ 3 must flow to a CSG on tab 11" pointer so the threshold isn't only buried in pitfalls.
• Severity: low — references list duplicates a fact. references/cal_levels.md, references/risk_determination_matrix.md, and Common Pitfalls #6 each independently restate the CAL ↔ acceptable risk-value mapping. Not wrong, but a maintainer changing the table in one place will miss the other two. Add a comment in cal_levels.md noting it's the canonical source so future edits are routed there.

Suggested edits (not applied this pass)

1. Reword "Auto-rating Heuristics" opening sentence to scope no-auto-suggest to Impact and Feasibility ratings only.
2. Add Windows shell variant under Step 4.
3. Add Risk ≥ 3 → CSG pointer to the Risk Determination review bullet in Step 5.
4. Mark references/cal_levels.md as canonical source for the CAL ↔ risk acceptance mapping.

Applied this pass

None — all four suggested edits touch substantive prose, not typo / frontmatter territory. Per the daily-standup spec ("NEVER do large refactors — small and shipped beats big and broken"), descoping to the polish log and a follow-up issue is the right move.

Overall verdict

tara-builder.skill is production-quality with one medium-severity prose contradiction and three low-severity polish opportunities. Description fits the 1024-char budget with headroom. Trigger phrases cover formal and casual phrasings. Pipeline linkage to CS Concept is declared. Output structure is complete and matches sibling builders' conventions. Ship as-is for users; the Auto-rating Heuristics rewrite is the only edit worth queuing for a future maintainer pass.

Severity: low overall, with one medium item flagged for follow-up.

Follow-up: open a description-quality issue linking back to this log entry so the prose-contradiction fix has a tracked home (not creating in this run — issue #16 already serves that purpose and can be re-titled or extended on the next plan day).