From 830670f2885753eb1d332c31f349f1e82e1c313f Mon Sep 17 00:00:00 2001 From: Dave Date: Fri, 3 Jul 2026 23:45:29 -0400 Subject: [PATCH] docs(#1867): clarify Step 9.5 manual element-extraction is by-design (review Minor 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit trek-e's re-review asked to either mechanize the Step 9.5 element extraction or add an inline note justifying why it stays manual, so a future maintainer doesn't read it as an oversight. Verified the premise: the requirement-side edge-probe path (spec-phase Step 5.5) it mirrors is ALSO a hand-populated heredoc + fail-loud placeholder guard — not a mechanical parse. The UI probe mirrors that idiom verbatim. Mechanizing would be worse: a UI-SPEC has no single machine-parseable "elements" column (surfaces are spread across the design-token tables, Copywriting, and researcher-named prose), so a regex/table parse would fail-OPEN (miss a prose-named surface, or feed a design-token row as a bogus element). Expanded the inline comment to state the parity + the fail-open rationale explicitly. No logic change; regenerated the workflow size baseline and the 16 golden-install-parity fixtures for the +847 B comment. Refs #1867 Claude-Session: https://claude.ai/code/session_017vYn26e3nkDNxcpty1ciPJ --- gsd-core/workflows/ui-phase.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/gsd-core/workflows/ui-phase.md b/gsd-core/workflows/ui-phase.md index a39847af8..2d58e840f 100644 --- a/gsd-core/workflows/ui-phase.md +++ b/gsd-core/workflows/ui-phase.md @@ -317,10 +317,19 @@ if [ -z "$UI_PROBE_JS" ]; then fi fi -# Element extraction: read the researcher-authored UI-SPEC prose (the described surfaces — the -# Design System / Copywriting rows and any element the researcher named) and write ONE object per -# UI element/surface: {"id","text"} where text is the prose describing it. Populate the heredoc from -# the UI-SPEC; the placeholder guard below fails loud on a forgotten substitution (never a no-op). +# Element extraction (MANUAL BY DESIGN — not an oversight): the agent reads the researcher-authored +# UI-SPEC prose (the described surfaces — the Design System / Copywriting rows and any element the +# researcher named) and writes ONE object per UI element/surface: {"id","text"} where text is the +# prose describing it. This mirrors spec-phase Step 5.5's edge-probe REQS_JSON step VERBATIM — a +# hand-populated heredoc guarded by the fail-loud check below — the established, shipped +# pattern for feeding a probe from a prose spec. It is NOT mechanized on purpose: a UI-SPEC has no +# single machine-parseable "elements" column — surfaces are distributed across design-token tables +# (Design System / Typography / Color), the Copywriting section, and prose the researcher names, so a +# regex/table parse would fail-OPEN (miss a prose-named surface, or feed a design-token row as a bogus +# element). The agent-authored heredoc + fail-loud guard is the conservative choice, identical to the +# requirement-side edge-probe path (RR-04). If a future UI-SPEC gains a canonical element table, +# revisit to parse it. Populate the heredoc from the UI-SPEC; the guard below fails loud on a +# forgotten substitution (never a no-op). ELEMENTS_JSON=$(mktemp "${TMPDIR:-/tmp}/ui-probe-elements-XXXXXX") && mv "$ELEMENTS_JSON" "${ELEMENTS_JSON}.json" && ELEMENTS_JSON="${ELEMENTS_JSON}.json" || exit 1 cat > "$ELEMENTS_JSON" <<'JSON' [