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

aspice-assessment-builder polish log

Polish target for W20 (issue #5). Reviewer: autonomous daily-standup task.

---

2026-05-14 — first POLISH pass

Mode: POLISH (Thursday) File reviewed: skills/aspice-assessment-builder.skill (ZIP archive; SKILL.md is 4,705 bytes / 95 lines). DoD recap (from docs/weekly/WEEK-2026-W20.md): confirm the 13-tab output list in the description matches the actual builder schema, and the trigger list mentions both v3.1 and v4.0.

DoD verdict

DoD check	Result
13-tab list matches builder schema	PASS
Trigger list mentions v3.1 and v4.0	PARTIAL — versions are in the description's opening clause but not in the "Use this skill whenever..." trigger list

What's good

• 13-tab list is exact. Cross-checked the SKILL.md "Output structure (13 tabs)" table (rows 00–12) against the tabs list in scripts/generate_aspice_assessment.py. All 13 entries match one-for-one, in order: Title Page, Document Control, Assessment Scope, Process Reference Model, Process Assessment Model, BP Assessment, GP Assessment, PA Rating, Capability Level, Capability Profile, Strengths/Weaknesses, Assessor Sign-off, References. The frontmatter description's "Produces 13 tabs including ..." partial enumeration names only real tabs and the count is correct. This is the primary DoD check and it passes cleanly — no drift between doc and schema.
• Frontmatter is clean. Both required keys present (name, description); no drift fields; YAML parses without complaint. Description is ~530 / 1024 chars — very comfortable headroom for a polish-only rewrite.
• The ASPICE rating algorithm section is accurate. The CL0–CL5 determination ladder in SKILL.md matches the pa_mapping in the generator (PA1.1, PA2.1–2.2, PA3.1–3.2, PA4.1–4.2, PA5.1–5.2) and the standard ASPICE PAM aggregation rule (each level needs the level below achieved AND both of its PAs ≥ Largely). Mentor-quality content, not filler — a junior assessor could rate a process correctly from this section alone.
• N/P/L/F indicator scale is introduced once, early, and reused consistently. Defined in the intro paragraph and echoed in Step 3 and the tab table. No ambiguity.
• Workflow is correctly ordered — scope capture → enumerate processes/practices → rate indicators → generate → review. The Step 5 review checklist (BP/GP evidence completeness, indicator ratings, PA aggregation, achieved CL) maps to the exact tabs a human would sanity-check.

What to fix

1. DoD partial miss: v3.1 / v4.0 are not in the trigger list. The versions appear in the description's first clause ("ASPICE PAM v3.1/v4.0 process assessment workbook") but the "Use this skill whenever the user needs to ..." trigger list does not name them. A user invoking with "run an ASPICE v4.0 assessment" still matches on "ASPICE ... process assessment", so trigger reliability is not broken — but per the strict W20 DoD this is the one open item. Severity: low.

2. No workflow step instructs reading the bundled references. The archive ships references/aspice_pam_3_1.md and references/methodology.md, but unlike item-definition-builder (which has an explicit "Step 2 — Read the references"), this SKILL.md never tells Claude to read them before generating. The reference content is therefore dead weight at runtime. Severity: low.

3. References directory has no v4.0 companion file. The skill advertises v3.1/v4.0 support and the References tab lists "ASPICE PAM v4.0" / "ASPICE PRM v4.0", but references/ only contains aspice_pam_3_1.md. A v4.0 reference (or a note that the v3.1 file covers both with deltas called out) would close the gap. Severity: low, observation.

4. .placeholder cruft file in the archive. unzip -l shows an empty aspice-assessment-builder/.placeholder — almost certainly a leftover empty-dir marker from packaging. Harmless but untidy; worth dropping next time the .skill is repackaged. Severity: low, observation.

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 the four findings match that list: #1 is an editorial trigger-coverage rewrite, #2 is a workflow-content addition, and #3/#4 are archive-content changes. No edits committed today. Captured here for the next human review pass.

Minimal proposed rewrite of the description — folds v3.1/v4.0 into the trigger list and adds the CL range, still well under 1024 chars, 13-tab claim untouched:

description: Generate a multi-tab ASPICE PAM v3.1/v4.0 process assessment workbook
  with capability level ratings, base practices, generic practices, and process
  attribute assessments. Produces 13 tabs including Title Page, Document Control,
  Assessment Scope, Process Reference Model, Process Assessment Model, BP/GP
  assessments, Capability Level determinations, strengths/weaknesses analysis, and
  assessor sign-off blocks. Use this skill whenever the user needs to conduct or
  document an ASPICE v3.1 or v4.0 process assessment, evaluate process maturity,
  rate capability levels (CL0-CL5), or create audit-ready assessment evidence.

For finding #2, the minimal fix is a one-line addition to Step 2 (or a new half-step): "Before generating, read references/methodology.md and references/aspice_pam_3_1.md for the PA aggregation rules and indicator-rating guidance." — left for human review since it is workflow content, not a surgical fix.

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

• SKILL.md uses ASCII hyphens for step headers (### Step 1 - Capture ...) where hara-builder and cs-concept-builder use em-dashes (### Step 1 — ...). Purely cosmetic; not worth an autonomous edit, but a suite-wide style pass could normalize it.
• The SKILL.md has no "Files in this skill" tree block (item-definition-builder and the safety builders do). Optional, but adding one would make the .placeholder cruft and the missing v4.0 reference visible to anyone reading the skill. Docs item, not a polish item.
• The generator is a single clean script (generate_aspice_assessment.py) plus the shared recalc.py / office/soffice.py helpers — consistent with the rest of the suite. The tabs list at the bottom of the script is the source of truth for the 13-tab claim and is easy to diff against SKILL.md on future passes.

Severity roll-up

Finding	Severity	Action
v3.1/v4.0 absent from trigger list	low	proposed rewrite drafted; await human review
No step instructs reading references/	low	one-line Step 2 addition proposed; await human review
No v4.0 reference file in archive	low (obs)	flagged for human / repackage pass
.placeholder cruft in archive	low (obs)	flagged for human / repackage pass

No code edits committed in this run. Issue #5 stays open with this log linked from the journal entry. This is the third consecutive POLISH finding with the same core shape — fundamentals are sound (13-tab list exact, rating algorithm accurate, frontmatter clean) but a formal trigger phrase (here: the version numbers) lives outside the active trigger list. hara-builder (#3, "safety goal"), cs-concept-builder (#4, "CSR derivation"/"CAL allocation"), and now aspice-assessment-builder (#5, "v3.1/v4.0") all shipped this pattern. The W21 PLAN should treat a suite-wide trigger-coverage DoD audit as a first-class target rather than continuing to catch one per POLISH day.