feat(migrate): use numeric labels for clarify options (a11y for non-Latin keyboards)

[pamdehesa]

Problem

The Clarify phase presents its answer options with Latin letter labels (> A) foo, > B) bar, up to H) in some questions). Users who type on keyboards without the Latin alphabet — Arabic, Chinese, Cyrillic, Greek, Hebrew, Japanese, Thai, and others — cannot easily produce those letters at the prompt. Numbers are on every keyboard layout.

The Clarify phase is the very first user-facing interaction in every migration flow (gcp-to-aws, heroku-to-aws, ai-only). A friction point here can quietly filter out non-English builders from ever completing a migration plan. It's a small accessibility fix that widens the plugin's reachable audience for zero functional cost.

Fix

Renumber every letter-labeled answer option — and every internal reference to those labels — from A/B/C/D/… to 1/2/3/4/… across the 7 Clarify markdown files:

• skills/heroku-to-aws/references/phases/clarify/clarify-interview.md (DSL reference implementation)
• skills/gcp-to-aws/references/phases/clarify/clarify.md
• skills/gcp-to-aws/references/phases/clarify/clarify-global.md
• skills/gcp-to-aws/references/phases/clarify/clarify-compute.md
• skills/gcp-to-aws/references/phases/clarify/clarify-database.md
• skills/gcp-to-aws/references/phases/clarify/clarify-ai.md
• skills/gcp-to-aws/references/phases/clarify/clarify-ai-only.md

Every reference within each file renames together so option labels and every reference to them stay in sync:

• User-facing option labels — > A) foo → > 1. foo (multi-line) or > 1\) foo | 2\) bar (inline, see note below)
• Interpret rules — - A → value / A -> value → - 1 → value / 1 -> value
• Defaults — **Default:** A →, Default: A —, Default to **A** all rename consistently
• Prose references — If A:, Option B, user selects B, recommend A, same as default (B), maps to A, otherwise B →
• Cross-question references — Q1 = A or B → Q1 = 1 or 2, Q5 != A → Q5 != 1, Q14 = D + F → Q14 = 4 + 6
• Combination-pattern tables — | B + any other | → | 2 + any other |, | B (harness) + A (no memory) | → | 2 (harness) + 1 (no memory) |
• Defaults / assumption-sheet tables — the summary tables that list each question's default option

Inline multi-option rows (> A) foo | B) bar | C) baz) become > 1\) foo | 2\) bar | 3\) baz with backslash-escaped parens. Necessary because dprint would otherwise canonicalize the leading 1) to 1. and leave the mid-line 2) 3) untouched, breaking the row's visual consistency. The escapes render as 1) 2) 3) in the final markdown.

Structural taxonomy references keep the same A–H letters:

• Category names (Category A, Category F, Cat B)
• Letter ranges ((A–F), (A-F))
• Non-option letters (A/B test, Series B, Pre-Series B, C extensions, C/C++, Rust/C/C++, N/A)
• The Category-flow table in clarify.md (| A (always) |, | B or C |)

Verification

Docs-only change. No code, no schema, no runtime behavior. The LLM interprets letter- or number-labeled options equally well; the payoff is on the human side.

The renumbering is a straight A→1, B→2, …, H→8 within each question. Within any given question, letters were assigned sequentially, so a numeric relabel preserves ordering and mapping semantics.

Every touched file was scanned after transformation to confirm no stray letter reference remained inside the option-answer contexts, while every structural taxonomy reference (Category X, Cat X, A/B test, Series B, ranges) is still present.

Rebased on latest main (2026-08-28). Conflicts with recently-added Q7 auto-resolve block (clarify-ai-only.md), Q18 auto-resolve (clarify-ai.md), Q23 LiteLLM/OpenRouter defaults (clarify-ai.md), Step 0 compatibility check (clarify.md), and the new App Engine Q7b question (clarify-compute.md) all resolved by keeping the new content and renumbering the letters it added.

Test plan

• dprint check on all 7 changed files — 0 errors
• markdownlint-cli2 on all 7 changed files (repo-wide run over 860 files) — 0 errors
• frontmatter-validator on heroku-to-aws (7 phase files), agent-advisor (11), gcp-to-aws (0, prose skill) — all OK
• node --test migrate/plugins/migration-to-aws/tests/tools/frontmatter-validator.test.ts — 62/62 pass, 0 fail
• Spot-check DSL reference (clarify-interview.md): every option label, Interpret bullet, Default line, and Defaults-summary row uses numbers; no stray A/B/C reference remains
• Spot-check largest gcp file (clarify-ai.md): combination tables and cross-question references use numbers consistently; Category F/G/H headings unchanged
• Structural refs preserved: Category [A-H] headings, Cat B rows, (A–F) ranges, A/B test, Series B, C extensions still present in the diff-unchanged regions

Not run locally (needs full mise install):

• mise run security (bandit, semgrep, gitleaks, checkov, grype) — docs-only change, no code touched
• mise run shared:check — no skills/shared/ files touched, so vendored copies unaffected

Both should pass in CI.

[herosjourney]

Nice catch on the accessibility gap — letters are a real barrier on non-Latin keyboard layouts, and the mechanical renumbering is careful. I checked every letter/number cross-reference in clarify-compute.md, clarify-database.md, clarify-global.md, clarify.md, and clarify-interview.md (Interpret rules, defaults, cross-question refs like Q5 = A, combination tables) and they all convert cleanly and consistently. Structural taxonomy (Category A–H, A/B test, Series B, N/A, (A–F) ranges) is correctly left alone everywhere.

Two things to fix before merge:

1. Two questions with >8 options are only half-converted (see inline comments). The renumbering logic seems to have stopped at H→8 and left I/J/K/L/... as letters, so those two questions (repeated in both clarify-ai.md and clarify-ai-only.md) still require typing a Latin letter — the exact friction this PR sets out to remove.

2. This PR only touches migrate/plugins/migration-to-aws/.... On current main, advisor/plugins/aws-startup-advisor/skills/{gcp-to-aws,heroku-to-aws}/references/phases/clarify/*.md are byte-identical mirrors of these same files (kept in sync by the repo's cross-plugin drift check). If this merges as-is, migrate gets numeric options while advisor keeps letters — the same kind of doc/behavior drift flagged in #229. Worth applying the same fix to the advisor/ copies in this PR.

Also flagging: this branch is quite stale relative to main (predates the #229 Dynos/Fargate fix, the agent-advisor phases work, and the advisor plugin 2.0.0 bundle) and currently shows as conflicting. Will need a real rebase, not just a conflict resolution pass.

[pamdehesa]

Thanks for the careful review — all three items addressed in the new revision (force-pushed):

1. Full alphabet extended. The renumbering now runs A→1 through Z→26, so Q17 (special features, 10 options) and Q19 (source model, 19 options) fully convert. No I/J/K/L/... letters remain in any option row. The renumbering script's L2N map now covers all 26 uppercase letters instead of just A–H.

2. Applied to the advisor mirror. Same fix now landed in advisor/plugins/aws-startup-advisor/skills/{gcp-to-aws,heroku-to-aws}/references/phases/clarify/*.md. Verified locally with mise run drift:check → OK (260 identical, 25 allowlisted across 6 skill trees). No new drift-allowlist entries needed.

3. Real rebase on main. Branch is now rebased on 0621f66 (2026-08-28 main), not just conflict-resolved. All the recent additions to the affected files pick up: Q7/Q18 auto-resolve blocks, Q23 LiteLLM/OpenRouter defaults, Step 0 compatibility check, and the new App Engine Q7b question. Their letter refs are renumbered too.

Also worth flagging — a couple of edge cases the mechanical pass missed and I fixed manually so the whole file stays consistent:

• Protected common single-letter idioms (N/A, Y/N, I/O) so Q8 → N/A doesn't become Q8 → 14/A etc.
• Q1 includes D/E/F (slash-joined option refs) — previously only D converted; now catches the full chain.
• Three prose-inside-table-cell references that no regex was going to catch cleanly (E is the long pole, Q14 = B only, An explicit user answer of A).

Local checks re-run on the new revision:

• dprint check — 0 errors
• markdownlint-cli2 — 0 errors across 860 files
• frontmatter-validator on migrate + advisor × {heroku-to-aws, agent-advisor, gcp-to-aws} — 6/6 OK
• frontmatter-validator.test.ts — 62/62 pass
• drift:check — OK

Let me know if anything else needs to change.

[herosjourney]

Re-reviewed the update — both issues from my last pass are resolved:

• >8-option questions: the source-model question (19 options in clarify-ai.md, 12 in clarify-ai-only.md) and the special-features question (10 options in both) are now fully numbered with no stray letters. Downstream Interpret → Default: lines are consistent with the new numbers.
• Advisor mirror: all 7 files now land under both migrate/plugins/migration-to-aws and advisor/plugins/aws-startup-advisor, and they're byte-identical between the two.
• Branch state: rebased cleanly onto current main, shows as mergeable.

Side note, not a bug: the inline pipe-separated option lists now render as 1\) Gemini Flash | 2\) Gemini Pro | ... with escaped parens. Confirmed this is dprint fmt (per the repo's dprint.json) auto-escaping N) inside blockquotes so renderers don't parse it as an ordered-list marker — expected formatter output, not a regression.

Re-swept all 14 changed files for leftover letter options; none found. LGTM.

[leon1418]

[🤖 AI review 🤖]

Finished reviewing PR #255 rev c02a78c with 2 comments.

Excellent accessibility improvement — renumbering option labels from Latin letters to numbers benefits every user on a non-Latin keyboard layout, and there are a lot of them. The A→1, B→2, … H→8 substitution is mechanically correct across all 14 files, cross-plugin parity is perfect (all 7 advisor↔migrate pairs are byte-identical), and structural taxonomy references (Category A–H, Cat B, A/B test, Series B, C extensions) are correctly preserved.

Two stray letter references survived the transformation:

1. clarify-global.md Q2 defaulted semantics — "answer 8" was updated but "chosen_by: \"user\" for H" on the same line still says H instead of 8. (Nit — see inline)
2. clarify-compute.md Q7b default line — the bold **Default:** **A** (compute_model: \"managed_platform\") was not converted. The interpret block above was correctly changed (4 -> same as default (1)), but the prose default line still says A. (Nit — see inline)

Neither is functionally critical — the LLM interprets the surrounding numeric context fine, and the interpret rules are correct. Fixing them is a consistency polish.

Validation evidence:

• Cross-plugin parity: all 7 file pairs verified byte-identical after normalizing path prefixes ✅
• Stray letter scan: grep for option-context letter references in added lines found only the 2 Nits above ✅
• Structural refs preserved: Category headings, Cat B, A/B test, Series B, C extensions all intact ✅
• PR description test plan: dprint, markdownlint, frontmatter-validator, 62/62 tests all reported passing by author (not verified by reviewer)

CI: 0 check runs reported. Merge status: MERGEABLE. Approvals: REVIEW_REQUIRED (0 approvals). Not approved.

[leon1418]

[🤖 AI review 🤖] Nit #2 (not in diff — unchanged line): In clarify-compute.md Q7b, the prose default line reads:

Default: A (compute_model: "managed_platform")

This should be 1 to match the renumbering. The interpret block directly above was correctly changed (4 -> same as default (1)), but this bold prose line was missed because it was outside the diff hunk. Same applies to the migrate/ copy.

Both Nits also need to be mirrored to the migrate/plugins/migration-to-aws/ copies to maintain cross-plugin parity.

[pamdehesa]

Thanks — both nits fixed in a44d3e3.

• clarify-compute.md Q7b: **Default:** **A** → **1**
• clarify-global.md Q2 semantics: for H → for 8

Mirrored the same edits to the migrate/ copies. Verified advisor/ and migrate/ mirrors stay byte-identical after the change (diff -q clean on both files). Ready for another look.