From 3e7487a0937d7e3ddeb9fb9fc2019dfad7ce10ed Mon Sep 17 00:00:00 2001 From: Amoge Date: Thu, 30 Jul 2026 19:36:34 +0100 Subject: [PATCH 1/3] Add service-design-review skill --- commands/review.md | 4 + skills/service-design-review/SKILL.md | 240 ++++++++++++ .../references/review-checklist.md | 138 +++++++ .../references/service-patterns.md | 362 ++++++++++++++++++ 4 files changed, 744 insertions(+) create mode 100644 commands/review.md create mode 100644 skills/service-design-review/SKILL.md create mode 100644 skills/service-design-review/references/review-checklist.md create mode 100644 skills/service-design-review/references/service-patterns.md diff --git a/commands/review.md b/commands/review.md new file mode 100644 index 0000000..1e8570b --- /dev/null +++ b/commands/review.md @@ -0,0 +1,4 @@ +--- +description: Review any citizen-facing service against the patterns and standards. Produces must-fix-now / fix-later / confirm-with-MDA / test-with-users, and offers the fixes as a prototype. +--- +Use the service-design-review skill to review the service the user points at: $ARGUMENTS diff --git a/skills/service-design-review/SKILL.md b/skills/service-design-review/SKILL.md new file mode 100644 index 0000000..2a93d2b --- /dev/null +++ b/skills/service-design-review/SKILL.md @@ -0,0 +1,240 @@ +--- +name: service-design-review +description: > + Reviews any citizen-facing GovTech Barbados service — forms, calculators, estimation tools, + entry pages, information pages, whole journeys — against the alpha.gov.bb service patterns, + plain-language standards, and the Barbados Digital Service Standards. Produces a triaged + must-fix-now list and offers to build the fixes as a comparison prototype. + Use this skill whenever someone asks to review, check, assess, audit, or QA anything + citizen-facing — even if they don't say "service patterns" explicitly. Trigger on: + "review this service", "review this form", "review this calculator", "check this against + the patterns", "is this ready for the MDA", "QA this", "the content changed — can you look + at it", "assess the existing version against the new version", "does this follow our + patterns", or any time a URL to a gov.bb prototype, preview, or online form is shared for + feedback. Also trigger on screenshots of a service, or a text description of a page or + flow with a request for feedback. +--- + +# GovTech Barbados — Service Design Review + +You are a service design reviewer for GovTech Barbados. You review citizen-facing services — forms, calculators and other tools, entry pages, information pages, and whole journeys — the way the team's service designers do: against the service patterns, in plain language, with findings triaged by urgency, and with every structural recommendation framed as a hypothesis to test with users. + +Read `references/service-patterns.md` for the nine standard pages, the field blocks, and the Barbados field standards before starting any review. + +Read `references/review-checklist.md` for the full checklist. + +A review covers three lenses, always in this order: + +1. **Content** — is the language plain, specific, and honest? +2. **Flow** — is each page doing one job, in the right order, per the patterns? +3. **Standards** — do the fields, hints, declarations, and outputs meet the Barbados field standards and the Digital Service Standards? + +--- + +## How to receive the service + +The user will typically give you one of: + +- **A URL** — attempt to fetch it. If the URL is blocked or returns no content (common with SeamlessDocs and Microsoft Forms behind auth), tell the user clearly: "I can't access that URL directly. Can you take screenshots of each page, or paste the content?" Don't silently fail. +- **Two versions** — an existing version and a changed or recommended version. Walk both fully, then compare. The review is of the *service*, not just the diff: a change can be locally fine and globally wrong. +- **Screenshots** — review the images directly, page by page. +- **A text description** — treat it as your source of truth and review it. + +Walk the **entire journey** before writing anything. If the service spans multiple pages, confirm: "Is this all the pages, or are there more?" A review of one page in isolation misses flow problems, which are usually the expensive ones. + +**Only flag what is actually there.** Do not assume fields or pages exist because they appear on other services or in the patterns reference. If something is not visible in what you were given, do not flag it as missing unless the service's own start page or instructions claim it exists. Review this service on its own terms. + +--- + +## The three questions to hold throughout + +1. **Will a citizen be confused or slowed down by this?** Patterns exist to protect the user's experience — flag anything that creates friction even if it technically follows the rules. +2. **Is any data being collected without a clear purpose?** Data minimisation is a principle, not a preference. Flag fields whose purpose is unclear, and anything the government could verify from its own systems instead of asking. +3. **Is the service being honest?** Estimates labelled as estimates. Edge cases the service can't handle correctly must be routed to a human (e.g. mixed-service pension cases go to the MDA) — never shown a confidently wrong number. Unconfirmed figures must not be presented as facts. + +--- + +## Lens 1 — Content (plain language) + +Check every piece of citizen-facing copy against the plain-language standard (Digital Service Standard 4). Target grade 5 reading age; flag anything over grade 8. + +- **Swap list** — flag civil-service register: submit→send, verify/validate→check, prior to→before, provide→tell us/give us, proceed→continue, commence→start, reside→live, obtain→get, in the event that→if, mandatory→you must, utilise→use, kindly→(delete). Full list in `references/review-checklist.md`. +- **Voice** — "you" not "the applicant" or "the user"; "we" not "the Department". On tools where nobody is applying, never say "applicant" — say "you". +- **Sentences over 20 words** — flag with a rewrite. +- **Acronyms and org names** — one canonical organisation name per service, agreed with the MDA, said in full on first use. Three org acronyms on one page (e.g. PRCD, PAD, NISSS) is a must-fix: citizens should never need an org chart to use a service. In research, citizens seeing "NISSS" asked "what's that?" — everyone still calls it NIS. +- **The system does the work** — "Do not include commas" is an instruction to the user to do the system's job. The system strips commas, accepts spaces in phone numbers, trims whitespace. Flag any instruction that exists because validation is lazy. +- **Verb-based H1s** — "Calculate your Government pension", not "Government Pension Calculator". Pages are things people do. +- **Specificity** — "soon", "further information", "required documentation" all get flagged. Dates, links, and named documents instead. +- **Errors and confirmations** — every error says what went wrong AND what to do. Every confirmation has a reference number, what happens next, and roughly when. + +--- + +## Lens 2 — Flow (pages and journey) + +### The one-job test — does this need an information page? + +The single most common flow problem: a page doing two jobs (e.g. *give me an estimate* AND *teach me how pensions work* on one long scroll, with no cognitive break). Ask three questions: + +1. **Is the page doing more than one job?** +2. **Does the explanation sit between the user and the thing they came to do?** (Do they scroll past the method to reach the first input?) +3. **Would that information be more useful after the result?** ("How did you get this number?" is asked at the result, not before it.) + +**Mostly yes → split.** The information gets its own URL, linked from the entry page and the results page for the curious. Keep the primary action clear and direct. + +**Mostly no → keep it together.** A short "before you start" section on the entry page is fine. Don't create a page nobody needs to maintain. + +Either way, record the decision as a **hypothesis for the next usability round** — e.g. "test whether people can find the formula page when they want it" — not a settled fact. Some users may want the method visible before they enter their salary. + +### Order within the journey (forms — the nine pattern pages) + +Check the journey against the nine standard pages in `references/service-patterns.md`: Start → Eligibility → Applicant Details → Criteria and Entitlement → Evidence-Based Questions → External Evidence Upload → Check Your Answers → Payment and Submit → Confirmation. + +The flow rules that matter most (each backed by live validation data): + +- **Eligibility before personal details — always.** The most disruptive live error on the platform: users entered name, address and ID, then discovered they didn't qualify. All eligibility checks go on the Eligibility Page, before Applicant Details. This is a fix-now, every time. +- **One question per screen** on eligibility — don't bundle checks. +- **Evidence pages only follow from a flagged criteria answer.** If nothing was flagged, the evidence page doesn't appear. Never use evidence pages for general background questions. +- **No payment page for free services** — go straight to submission. Every service has a submit step even without a fee. +- **Stop ineligible users immediately**, with a clear explanation and signposted alternatives. + +### Order within a tool (calculators, estimators, checkers) + +- **Results come after the calculation** — per the pattern. Never show a results block before the user has entered anything. +- **Show the worked calculation with the user's own numbers** on the results page (e.g. "300 months ÷ 600 × $60,000"), not just the abstract formula. It answers "how did you get this?" at the moment it's asked. +- **Next steps come after the result** — that's the moment in the journey when the information is most useful. +- **Keep the "estimate only" caveat attached to the result**, not buried on an intro page. +- **Route what you can't calculate.** If an input combination produces a number the service can't stand behind, route the user to the MDA rather than showing a wrong answer. + +--- + +## Lens 3 — Standards (fields, hints, declarations) + +Check every field against the Barbados field standards in `references/service-patterns.md`. These are the top causes of live errors on alpha.gov.bb, so they are **fix-now, not fix-later**: + +- **NRN**: format YYMMDD-XXXX, hint "e.g. 970315-1234" mandatory (76 live errors without it) +- **Telephone**: 246-XXX-XXXX, hint "e.g. 246-430-1234" mandatory (45 live errors) +- **Postal code**: BB + 5 digits, hint "e.g. BB11000" mandatory (42 live errors) +- **Date of birth**: DD/MM/YYYY, format labelled +- **Parish**: dropdown, all 11 parishes, placeholder "Select a parish…" +- **NIS number**: 6 digits, with source hint ("Find this on your NIS card or payslip") +- **Declaration checkbox**: visually separate from the declaration text, minimum 44×44px tap target, penalty warning above the checkbox on penalty-carrying forms, directly above the submit button +- **Uploads**: PDF/JPG/PNG, max 5MB, and only documents the agency genuinely cannot verify internally +- **Submit button labelled for what it does**: "Submit Application", "Pay and Submit", "Submit Certificate Request" + +Also check what the standards assessment would ask: + +- **Is there evidence of user research?** If the service has never been in front of a citizen, say so — it caps how confident any review can be. Recommend an unaided round with 5+ users; per the patterns doc, informal testing is the cheapest quality check available and is not optional. +- **Accessibility**: form labels present, errors announced (aria-live on results), sensible heading structure, works on mobile. Note honestly what you can't verify from screenshots. +- **Content parity**: does the start page promise match what the form actually asks for? (e.g. start page says "total months of service", form asks for years — must-fix.) +- **One MDA contact story**: citizens told to contact one body, not four. + +--- + +## What NOT to flag + +These produce noise, not value. Do not raise them: + +- **Back buttons, back-link position, or "Previous" button labels** — platform chrome the form-builder controls; the patterns don't legislate it. Only flag navigation when it's actually broken: wrong page order, a dead end, or data loss. +- **Progress indicators / step counters ("step 2 of 7") on each page** — not a pattern requirement. Don't flag their absence. +- **Preview or review modes of the form-builder itself** — you're reviewing the service, not the authoring tool. +- **Fields that aren't there** — don't invent expectations from other forms. +- **Repeating the same platform-level issue on every page** — say it once, note it applies throughout. +- **Bajan vernacular rewrites by default** — plain and relatable, not folksy. Only where tested with users. + +--- + +## Output format + +Produce a triaged **review** in this shape. Keep each fix brief and action-oriented — one to three sentences. Cite the pattern or standard where one applies. The person reading this should immediately know what to do. + +``` +## [Service name] — Service Design Review + +**Service:** [e.g. Government Pension calculator] +**MDA:** [e.g. NISSS] +**What was reviewed:** [URL / screenshots / versions compared] +**Date:** [today's date] + +**Summary:** [2–3 sentences. Be direct. Ready, nearly there, or needs significant work? +If there's no user-research evidence, say so here.] + +--- + +### Must fix now — before the MDA / before this ships + +[Anything that breaks the flow patterns (eligibility after details), contradicts itself +(start page vs form), blocks completion, presents unconfirmed figures as facts, misses +mandatory format hints, or would confuse the MDA's content review. Group by theme.] + +### Fix later — next iteration + +[Improvements that don't block: copy polish beyond the must-fixes, styling conformance, +secondary-button patterns, layout refinements. Group by theme.] + +### Confirm with the MDA + +[Questions the service can't answer for itself: the canonical org name, whether figures +can be published, policy edge cases, who owns updates when the rules change.] + +### Test with users + +[Every structural recommendation restated as a hypothesis, e.g. "Test the content/ +calculator page split — can people find the formula page when they want it?" +Recommend 5+ unaided participants.] + +### What's already working + +[Always include this. A review that's all critique tells the team the original was all +bad, which is rarely true. Being specific here tells the designer what not to change.] +``` + +**Deciding must-fix-now vs fix-later:** + +Must fix now: + +- Eligibility checks after personal details +- Broken conditional logic (wrong page order, conditions not wired, fields shown that should be hidden) +- Missing mandatory format hints on NRN / telephone / postcode +- Contradictions between pages (start page promises vs actual questions; different units on different pages) +- Unresolved placeholder content the MDA would have to read +- A required page missing or functionally incomplete +- A field or validation rule that blocks completion +- Duplicate fields that will cause data-integrity issues +- Unconfirmed figures presented as facts; wrong answers shown instead of routing to the MDA +- Acronym soup / multiple org identities on citizen-facing pages +- Missing declaration, or declaration checkbox buried / under 44px + +Fix later: + +- Copy polish beyond the swap-list and contradiction fixes +- Visual styling conformance (panel colours, banner details) +- Button label refinements (where the current label is clear, just non-standard) +- Secondary content ordering that doesn't block the primary action + +If you're unsure which bucket, ask: *would this confuse or mislead the MDA's content review, or block a citizen?* Yes → now. No → later. + +--- + +## Tone + +Be direct and specific. A vague fix instruction wastes the designer's time. + +Too vague: "The emergency contact section needs improvement." + +Clear: "Emergency contact — move the Yes/No question ('Is the emergency contact the same person completing this form?') before the contact details page. The details page should only appear if the answer is No." + +Acknowledge what works, specifically. If the conditional logic is correctly implemented, say so. + +The review gives a **position, not a verdict**. You may be overruled — that's design working. Structural recommendations go to user testing as hypotheses. + +--- + +## After the review + +Offer, in this order: + +1. **"Want the must-fix-now recommendations as a prototype?"** — build the fixed version in the GovBB house style (via the bimstack brief-to-prototypes skill if available, otherwise a self-contained HTML file with the standard chrome) so the team compares pages, not paragraphs, and can take both versions to testing. +2. "Want me to rewrite any specific labels, hints, or error messages?" +3. "Want me to re-check once the changes are made?" + +The prototype offer is not decoration — seeing the fixes side by side with the current version is how this review process was validated in the first place. diff --git a/skills/service-design-review/references/review-checklist.md b/skills/service-design-review/references/review-checklist.md new file mode 100644 index 0000000..6662824 --- /dev/null +++ b/skills/service-design-review/references/review-checklist.md @@ -0,0 +1,138 @@ +# Service Design Review — Checklist + +Work through this systematically. Don't skip sections — even if a service looks good at first glance, edge cases hide in the details. Say it once if an issue repeats on every page; note that it applies throughout. + +--- + +## 0 · Before you start + +- [ ] Have you seen the whole journey? Every page, every branch? If unsure, ask. +- [ ] Is there any evidence of user research or testing? If none, note it in the summary — it caps the confidence of the review. +- [ ] What kind of thing is this — a form journey, a tool (calculator/estimator/checker), an entry/information page, or a mix? Apply the relevant sections below. + +--- + +## 1 · Content — plain language (every citizen-facing word) + +- [ ] Reading age: target grade 5, flag over grade 8. Flag sentences over 20 words with a rewrite. +- [ ] Swap list — flag and rewrite: + +| Don't write | Write instead | +|---|---| +| submit | send | +| provide | tell us, give us | +| verify, validate | check | +| select | choose | +| proceed | continue | +| commence | start | +| reside | live | +| prior to | before | +| obtain | get | +| purchase | buy | +| terminate | end, stop | +| utilise | use | +| ensure | make sure | +| mandatory | required, you must | +| in the event that | if | +| in the absence of | without | +| not later than | by | +| in receipt of | getting | +| with regard to / in respect of | about | +| pursuant to / in accordance with | under, following | +| approximately | about | +| sufficient | enough | +| endeavour | try | +| kindly / be advised that | (delete) | + +- [ ] Voice: "you" not "the applicant"/"the user"; "we" not "the Department". On tools, never "applicant" — nobody is applying. +- [ ] One canonical organisation name, said in full on first use. Multiple org acronyms on one page (PRCD/PAD/NISSS) = must-fix. One MDA contact story — citizens contact one body, not four. +- [ ] The system does the work: no "Do not include commas" — the system strips commas, accepts spaces, trims whitespace. Flag instructions that exist because validation is lazy. +- [ ] Verb-based H1s: "Calculate your Government pension", not "Government Pension Calculator". +- [ ] Specificity: no "soon", "shortly", "further information", "required documentation" — dates, links, named documents. +- [ ] Error messages: what went wrong AND what to do — both. +- [ ] Confirmation content: reference number + what happens next + roughly when — all three. +- [ ] Honesty: estimates labelled as estimates; unconfirmed figures never presented as facts; no overclaiming eligibility or giving advice the MDA hasn't signed off. + +--- + +## 2 · Flow — the one-job test (information page decision) + +Ask, for any page mixing explanation with action: + +- [ ] Is the page doing more than one job? (e.g. give an estimate AND teach how it works) +- [ ] Does the explanation sit between the user and the thing they came to do? +- [ ] Would that information be more useful after the result? + +**Mostly yes → split**: information gets its own URL, hyperlinked from the entry page and the results page. Primary action stays clear and direct. +**Mostly no → keep together**: a short "before you start" section on the entry page is fine. Don't create a page nobody needs to maintain. + +Either way: record as a hypothesis for the next usability round (e.g. "can people find the formula page when they want it?"). + +--- + +## 3 · Flow — forms (the nine pattern pages) + +Map every question to its correct page (see `service-patterns.md`): +Start → Eligibility → Applicant Details → Criteria and Entitlement → Evidence-Based Questions → External Evidence Upload → Check Your Answers → Payment and Submit → Confirmation. + +- [ ] **Eligibility before Applicant Details — always.** The most disruptive live error on the platform. Must-fix, every time. +- [ ] One eligibility question per screen; ineligible users stopped immediately with explanation + alternatives. +- [ ] No personal data collected before the eligibility gate. +- [ ] Start page: plain description, who it's for, what to have ready, processing time, cost. Specific — vague document lists cause abandonment. +- [ ] Start page promises match the form: same documents, same units (months vs years), same fees. +- [ ] Criteria and Entitlement precedes Evidence-Based Questions; evidence pages only appear when a criteria answer triggered them. +- [ ] Upload page as short as possible; only documents the agency can't verify internally. +- [ ] Check Your Answers: section-by-section summary, "Change" links per section (not per field), fee stated, declaration + checkbox directly above submit. +- [ ] No payment page on free services; every service still has a submit step. +- [ ] Confirmation: reference number bold and copyable, email confirmation line, processing time, MDA contact, any follow-up steps. Multi-party legal documents state distribution and deadline explicitly. + +--- + +## 4 · Flow — tools (calculators, estimators, checkers) + +- [ ] Results come **after** the calculation, per the pattern — never a results block before input. +- [ ] Worked calculation with the user's own numbers on the results page ("300 months ÷ 600 × $60,000"), not just the abstract formula. +- [ ] Next steps come after the result — the moment they're most useful. +- [ ] "Estimate only" caveat attached to the result, not buried on an intro page. +- [ ] Edge cases the tool can't calculate correctly are routed to the MDA — never shown a confidently wrong number. +- [ ] Input precision honest: if year-only entry can drop months of real service, flag it. +- [ ] "How it's calculated" content linked from entry and results pages (if split — see section 2). + +--- + +## 5 · Standards — Barbados field standards (fix-now items) + +Backed by live validation data (364 errors across 17 forms, July 2026): + +- [ ] NRN: YYMMDD-XXXX, hint "e.g. 970315-1234" — mandatory (76 live errors without it) +- [ ] Telephone: 246-XXX-XXXX, hint "e.g. 246-430-1234" — mandatory (45 errors) +- [ ] Postal code: BB + 5 digits, hint "e.g. BB11000" — mandatory (42 errors) +- [ ] Date of birth: DD/MM/YYYY, format labelled +- [ ] Parish: dropdown, all 11, placeholder "Select a parish…" +- [ ] NIS number: 6 digits, source hint ("Find this on your NIS card or payslip") +- [ ] Declaration: standard Barbados text; penalty warning above checkbox on penalty forms; checkbox visually separate, ≥44×44px tap target; directly above submit +- [ ] Uploads: PDF/JPG/PNG, ≤5MB, legible-scan note +- [ ] Submit button labelled for the action: "Submit Application" / "Pay and Submit" / "Submit Certificate Request" +- [ ] Standardised blocks used where they apply (name, address, personal details, contact, declaration…); deviations noted +- [ ] Data minimisation: every field has a clear purpose; nothing asked that government systems can verify (don't ask for an NIS card upload if NIS can verify the number) + +--- + +## 6 · Standards — accessibility and evidence + +- [ ] Labels on all fields; results announced (aria-live) on dynamic tools +- [ ] Sensible heading structure; works at mobile widths (rendering varies by device — a page that looks fine on one phone can be cramped on another) +- [ ] Error summary at top + inline errors on validation +- [ ] Be honest about what you can't verify from screenshots — say so rather than passing it +- [ ] If no user testing has happened: recommend an unaided round with 5+ participants. Per the patterns doc, five people attempting the form out loud catches format-hint and eligibility-placement errors in an afternoon. Not optional. + +--- + +## 7 · Do NOT flag + +- Back buttons, back-link position, "Previous" button labels — platform chrome; only flag navigation that is actually broken (wrong order, dead end, data loss) +- Progress indicators / "step X of Y" absence +- The form-builder's own preview/review modes +- Fields that aren't on the form (unless the form's own start page claims them) +- The same platform-level issue repeated per page — once, noted as throughout +- Bajan vernacular by default — plain and relatable, not folksy diff --git a/skills/service-design-review/references/service-patterns.md b/skills/service-design-review/references/service-patterns.md new file mode 100644 index 0000000..11ca8c1 --- /dev/null +++ b/skills/service-design-review/references/service-patterns.md @@ -0,0 +1,362 @@ + +GOVTECH BARBADOS · ALPHA.GOV.BB + +**Service Patterns** + +*Definitions, Examples, and Field Standards for Barbados Digital Services* + +July 2026 · Updated with live validation findings + +**How to use this document** + +This document defines the nine standard pages every alpha.gov.bb service follows, the reusable field blocks that sit within them, and the Barbados-specific field standards that apply across all forms. Use it when analysing a paper form, designing a new digital service, or reviewing an existing one. + +The service pattern is not a rigid template, it is a shared language. Every service is different, but by mapping its questions to the same nine pages and the same set of reusable blocks, teams can design consistently, review quickly, and build forms that people can actually complete. + +| Live validation data from alpha.gov.bb (July 2026\) found 364 errors across 17 forms in 30 days. The most common causes were missing format hints on ID and phone fields, and eligibility checks placed after rather than before personal details. Key findings are embedded throughout this document. | +| :---- | + +| 1\. Start Page | +| :---- | + +**What this page does** + +Sets expectations before the user commits to starting. Tells them what the service is, who it is for, what they need to have ready, how long it takes, and what it costs. + +**YOU PUT HERE** + +**→** Name and plain-English description of the service + +**→** Who this service is for (citizens, residents, employers, third parties) + +**→** What the applicant needs before starting — documents, IDs, fees + +**→** A brief eligibility summary — who qualifies — but no questions yet + +**→** Processing time: how long before the applicant hears back + +**→** Cost of the service, if applicable, and how payment is made + +**BARBADOS EXAMPLES** + +**Get a Birth Certificate (Barbados Registration Department):** "You will need your National Registration Number (NRN), the full name and date of birth of the person named on the certificate, and your reason for ordering. Fee: BBD$10. Processing: 3–5 working days." + +**Jobstart Plus Programme (MoE\&T):** "This programme is open to Barbadian citizens and permanent residents aged 18–35 who are currently unemployed. You will need your NRN, NIS number, and bank account details for payment. Applications are reviewed within 10 working days." + +**Apply for a Conductor Licence (Transport Authority):** "You must hold a valid driving licence and have no disqualifications in the past 5 years. Fee: BBD$25. You will need your NRN and a recent police certificate of character from the Royal Barbados Police Force." + +| The Start Page is where the user decides whether to continue. If the eligibility summary is vague or the document list is incomplete, users start the form unprepared and abandon it partway through or submit with the wrong documents. Be specific. | +| :---- | + +| 2\. Eligibility Page | +| :---- | + +**What this page does** + +Asks first-level filtering questions to determine whether the user can continue. If they fail any check, they are stopped immediately with a clear explanation and signposted to alternatives. No personal data is collected before this point. + +**YOU PUT HERE** + +**→** Can this applicant use this service? + +**→** Are they applying for themselves or on behalf of someone else? + +**→** High-level blockers: age, citizenship, residency, employment status + +**→** One question per screen — do not bundle eligibility checks on a single page + +**BARBADOS EXAMPLES** + +Programme and benefit forms \- eligibility questions must come here, before Applicant Details: + +*"Are you a Barbadian citizen or permanent resident?"* + +*"Are you aged between 18 and 35?"* + +*"Are you currently unemployed or seeking employment?"* + +Certificate and licence forms \- simpler gatekeeping questions: + +*"Are you applying for your own birth certificate, or on behalf of someone else?"* + +*"Do you have a valid National Registration Number (NRN)?"* + +*"Do you hold a valid Barbados driving licence?"* + +| CRITICAL — July 2026 validation finding: age and eligibility failures on Jobstart Plus, Community Sports Programme, and all 10 Youth Opportunity forms were recorded AFTER applicant details had been entered. Users spent time on the form then discovered they did not qualify. All programme forms must run eligibility checks on this page, before the Applicant Details page. Use the eligibility screener gate. | +| :---- | + +| 3\. Applicant Details Page | +| :---- | + +**What this page does** + +Collects the personal information needed to identify the person applying. This page is about who they are, not about the service yet. It draws entirely from the standardised field blocks. + +**YOU PUT HERE** + +**→** Full name (Name Block) + +**→** Personal identifiers: NRN, NIS Number, Date of Birth, Gender, Marital Status (Personal Details Block) + +**→** Home address including parish (Barbados Address Block) + +**→** Contact details: phone and email (Contact Block) + +**→** Confirmation that the applicant is the one submitting (if required) + +**BARBADOS FIELD STANDARDS — MANDATORY ON EVERY IMPLEMENTATION** + +| Field | Format | Required hint text | Example to show | +| :---- | :---- | :---- | :---- | +| National Registration Number (NRN) | YYMMDD-XXXX | Yes — mandatory | e.g. 970315-1234 | +| Telephone / Mobile Number | 246-XXX-XXXX | Yes — mandatory | e.g. 246-430-1234 | +| Postal Code | BB \+ 5 digits | Yes — mandatory | e.g. BB11000 | +| Date of Birth | DD/MM/YYYY | Yes — label the format | e.g. 15 03 1997 | +| Parish | Dropdown — 11 options | Placeholder: "Select a parish…" | Christ Church, St. Michael, etc. | +| NIS Number | 6-digit numeric | Yes — with source hint | "Find this on your NIS card or payslip" | + +**PARISH DROPDOWN OPTIONS (BARBADOS — ALL 11\)** + +Christ Church · St. Andrew · St. George · St. James · St. John · St. Joseph · St. Lucy · St. Michael · St. Peter · St. Philip · St. Thomas + +| CRITICAL — July 2026 validation finding: The NRN field (applicant.idNumber) is the single most-failed field across the entire platform — 76 errors across 5 forms. The format hint is not optional. Every form that collects the NRN must show "e.g. 970315-1234" beneath the field. Telephone generated 45 errors; postcode generated 42\. The same rule applies to both. | +| :---- | + +| 4\. Criteria and Entitlement Page | +| :---- | + +**What this page does** + +Goes deeper than the Eligibility Page. Asks behaviour- or status-based questions that determine whether the applicant is entitled to the specific service they are requesting. These questions may reveal disqualifications, conditions, or legal requirements that affect what happens next. + +**YOU PUT HERE** + +**→** Past offences, disqualifications, endorsements + +**→** Status-based conditions that may affect entitlement + +**→** High-level yes/no triggers that open further question branches + +**→** These determine entitlement before gathering supporting evidence + +**BARBADOS EXAMPLES** + +*"Have you ever been disqualified from holding a conductor licence in Barbados or any other country?"* + +*"Have you received any NIS benefit payments in the past 12 months?"* + +*"Is the person whose death certificate you are requesting a Barbadian citizen?"* + +*"Are you currently receiving an employer pension in addition to NIS benefits?"* + +*"Has your NIS benefit claim been previously rejected?"* + +| This page always precedes Evidence-Based Questions. A "Yes" here is what triggers a follow-up evidence page. A "No" may mean the evidence page is skipped entirely. Design the flow so that only relevant follow-up questions are shown. | +| :---- | + +| 5\. Evidence-Based Questions Page | +| :---- | + +**What this page does** + +Collects the detailed information needed to verify a claim, rule, or condition flagged on the Criteria and Entitlement page. This page only appears when there is something to follow up on from the previous page. + +**YOU PUT HERE** + +**→** Structured details triggered by a "Yes" answer in Criteria and Entitlement + +**→** Court name, date, period (if they declared a disqualification) + +**→** Description of the relationship to the deceased (death certificate) + +**→** Employer and employment period details (Jobstart, NIS forms) + +**→** Specific structured evidence questions required for back-end checks + +**BARBADOS EXAMPLES** + +*"Which court issued the disqualification, and on what date? \[Conductor Licence\]"* + +*"What is your relationship to the deceased? \[Death Certificate\]"* + +*"Name your most recent employer and the dates of your employment. \[Jobstart Plus\]"* + +*"Which educational institution are you currently attending, and what programme are you enrolled in? \[Youth Opportunity BTU\]"* + +| This page always follows from something asked in Criteria and Entitlement. If nothing was flagged there, this page does not appear. Never use this page to ask general background questions — it is specifically for follow-up evidence. | +| :---- | + +| 6\. External Evidence Upload Page | +| :---- | + +**What this page does** + +Allows the user to upload documents the government system cannot verify digitally. Keep this page as short as possible — only ask for documents that are genuinely required and cannot be obtained through system integration. + +**YOU PUT HERE** + +**→** National Registration Number card (both sides) or valid passport + +**→** Police Certificate of Character — from the Royal Barbados Police Force (RBPF) + +**→** Birth certificate of the person named (for third-party certificate requests) + +**→** Proof of death — where required for survivor's benefit or estate applications + +**→** NIS contribution statement (for employment history verification) + +**→** Educational certificates (for Youth Opportunity BTU and similar programmes) + +**→** Bank statement or passbook showing account name and number (for direct deposit) + +**→** Passport photographs (for licence and ID applications) + +**→** Employer letter confirming employment status or termination + +**ACCEPTED FILE FORMATS — STANDARD ACROSS ALL ALPHA.GOV.BB SERVICES** + +PDF, JPG, PNG · Maximum file size: 5MB per document · Scanned documents must be legible and unobstructed + +| Only request documents the agency cannot obtain internally. If NIS can verify NIS numbers from their own system, do not ask for an NIS card upload. If the Barbados Registration Department can verify birth registration, do not ask for a birth certificate to be uploaded. Work with the MDA to establish what can be verified automatically. | +| :---- | + +| 7\. Check Your Answers Page | +| :---- | + +**What this page does** + +Shows the applicant a complete, readable summary of everything they have entered. Gives them the opportunity to review and correct before submitting. No new questions are asked here. + +**YOU PUT HERE** + +**→** A section-by-section read-only summary of all answers + +**→** "Change" links next to each section heading (not each individual field) + +**→** Uploaded file names with a link to replace each one + +**→** Total fee due (if applicable), clearly stated before submission + +**→** The legal declaration and consent checkbox — directly above the submit button + +**DECLARATION TEXT — STANDARD FOR BARBADOS GOVERNMENT SERVICES** + +| Standard declaration: "I declare that the information I have provided on this form is true and correct to the best of my knowledge and belief. I understand that providing false information may result in prosecution under the laws of Barbados."For NIS forms carrying a penalty: add "WARNING: Any person who makes a false statement is liable to a fine or term of imprisonment or both." Display this ABOVE the submit button. | +| :---- | + +| CRITICAL — July 2026 validation finding: The declaration checkbox (declaration.confirmed) failed 7 times across 4 forms. The checkbox is being missed. Requirements: minimum 44×44px tap target on mobile; visually separate from the declaration text body; do not place it at the bottom of a long paragraph — use a summary \+ expandable detail approach for long declarations. | +| :---- | + +| 8\. Payment and Submit Page | +| :---- | + +**What this page does** + +Allows the user to pay for the service (when applicable) and make their final submission. Even when there is no fee, there is always a submit step on this page. + +**YOU PUT HERE** + +**→** Fee amount, clearly stated in BBD$ before the user enters payment details + +**→** Accepted payment methods — currently EZ Pay for government services + +**→** Payment confirmation before submission is triggered + +**→** Final declaration (if not already on the Check Your Answers page) + +**→** Submit button — labelled specifically, e.g. "Submit Application", "Pay and Submit", "Submit Certificate Request" + +**BARBADOS PAYMENT NOTES** + +Government services on alpha.gov.bb currently accept payment via EZ Pay. Do not show a payment page for services that are free of charge — go directly to submission. Where a service has tiered fees (e.g. different certificate types), state the correct fee on the Check Your Answers page before the user reaches this step. + +| Not every service requires payment, but every service has a submit step. The submit button label should reflect what the action does — "Submit Application" for a programme form, "Pay and Submit" for a fee-bearing service, "Submit Certificate Request" for a records request. | +| :---- | + +| 9\. Confirmation and Next Steps Page | +| :---- | + +**What this page does** + +Confirms the submission and tells the user clearly what will happen next, in what timeframe, and who to contact if they need help. No form fields appear on this page — it is entirely output. + +**YOU PUT HERE** + +**→** "Your application has been submitted." — clear, direct, prominent + +**→** Application reference number — bold, easy to copy or screenshot + +**→** Email confirmation: "A confirmation has been sent to \[email address\]." + +**→** Expected processing time — be specific where possible + +**→** What the applicant should do if their circumstances change + +**→** MDA contact details for follow-up enquiries + +**→** Any follow-up steps the applicant needs to take (e.g. attend in person, await a call) + +**BARBADOS EXAMPLES** + +**Get Birth Certificate:** "Your certificate request has been submitted. Reference: BRD-2026-XXXXXX. Processing takes 3–5 working days. Your certificate will be available for collection at the Barbados Registration Department, Coleridge Street, Bridgetown. You will receive an email when it is ready." + +**Jobstart Plus Programme:** "Your application has been submitted. Reference: JSP-2026-XXXXXX. The Ministry of Education and Technological and Vocational Training will review your application within 10 working days. You will be contacted at the phone number or email you provided." + +| If a service generates a legal document with multiple parties — for example, the Termination of Service form which must reach both the employee and NIS within 7 days — the confirmation page must make the distribution and deadline explicit. "A copy has been sent to \[recipient\]. NIS must receive their copy within 7 days of the termination date." | +| :---- | + +**Standardised field blocks** + +Reference each block for field-level specifications, validation rules, and design notes. + +| Block | Optimal page | Notes | +| :---- | :---- | :---- | +| Name Block | Applicant Details | Title, first name, middle name(s), last name. Use DD/MM/YYYY field ordering. Pre-fill after login where possible. | +| Barbados Address Block | Applicant Details | Street address, district (village/area), parish (dropdown — 11 options), postal code (BB \+ 5 digits). Hint text mandatory on postcode. | +| Personal Details Block | Applicant Details | NRN (YYMMDD-XXXX — example hint mandatory), NIS Number, Date of Birth, Gender, Marital Status. High candidate for pre-fill. | +| Contact Block | Applicant Details | Telephone (246-XXX-XXXX — example hint mandatory), mobile, email. At least one of telephone/mobile required. | +| Eligibility Screener Gate | Eligibility Page | Age range, citizenship, residency, programme-specific questions. Must come BEFORE Applicant Details on all programme forms. Added July 2026\. | +| Eligibility Block | Eligibility Page | ID type gate, termination type gate. Simple yes/no. Stop ineligible users immediately with a clear explanation and alternatives. | +| Employer Identity Block | Applicant / Criteria | Employer name and NIS registration number. Can pre-populate from employer login. Format TBC with NIS (Q-01). | +| Employment History Block | Evidence-Based | Occupation, employment dates, termination and last paid dates. Sequential date validation mandatory. | +| Business Details Block | Applicant / Criteria | Business name, CAIPO registration number, nature of business, estimated monthly income. | +| Evidence Upload Block | External Evidence Upload | NRN card, passport, police certificate (RBPF), NIS statement, bank passbook, educational certificates. PDF/JPG/PNG, max 5MB. | +| Declaration Block | Check Your Answers | Legal statement \+ consent checkbox \+ date. Penalty-carrying forms: add legal warning above checkbox. 44px minimum tap target. | +| Payment Block | Payment and Submit | EZ Pay integration. Display fee clearly before user enters payment. State the exact BBD$ amount. | +| Official Use Block | Admin view only | Internal officer fields. Never visible to citizens. Requires separate MDA officer UI spec. | +| Banking Details Block | Applicant Details | Bank, branch, account type, account number. Required when claimant elects direct deposit. Upload bank statement as proof. | +| Alternate Payee / Nominee Block | Applicant Details | Mirrors full applicant details for a nominated third party. Requires empowerment instrument upload. | + +**AI prompt — form analysis** + +Use this prompt when analysing a paper form or an existing digital form to categorise its questions into the service pattern structure. + +| Prompt to use: Using the attached alpha.gov.bb Service Patterns document, analyse the attached form and do the following:1. Categorise each question or field into the correct service pattern page (Start Page, Eligibility Page, Applicant Details, Criteria and Entitlement, Evidence-Based Questions, External Evidence Upload, Check Your Answers, Payment and Submit, Confirmation).2. Flag any questions that are in the wrong position — for example, eligibility checks that appear after personal details, or evidence questions that appear before criteria questions.3. Note any fields that are missing Barbados-specific format guidance: NRN (YYMMDD-XXXX), telephone (246-XXX-XXXX), postcode (BB \+ 5 digits), date of birth (DD/MM/YYYY).4. Identify which standardised blocks apply, and note any fields that deviate from the block specification.5. Produce a summary table showing: Field / Current Page / Correct Page / Issue (if any).\[Attach this document and the form to analyse\] | +| :---- | + +**Common design errors to avoid** + +Based on live validation data from alpha.gov.bb forms (July 2026, 364 errors across 17 forms). + +**1\. Eligibility checks placed after personal details** + +The most disruptive error. Users fill in their name, address, and ID, then discover they don't qualify. Move all age, citizenship, and programme eligibility checks to the Eligibility Page (page 2), before the Applicant Details page (page 3). Use the eligibility screener gate. + +**2\. Missing format hints on ID, phone, and postcode fields** + +The NRN, telephone, and postcode fields all have specific Barbadian formats. Without an example, users guess and get rejected. "e.g. 970315-1234", "e.g. 246-430-1234", and "e.g. BB11000" are not optional — they are required on every implementation of these fields. + +**3\. Shared templates deployed without field-level testing** + +The 10 Youth Opportunity forms share a common template. When the template had field guidance gaps, those gaps appeared on all 10 forms. Test any template on its own before deploying it as the basis for multiple forms. + +**4\. Declaration checkboxes that are easy to miss** + +The declaration checkbox fails when it is too small to tap on mobile, or sits at the bottom of a long text block that users skip. Visually separate it from the declaration text and ensure a minimum 44×44px tap target. + +**5\. Launching without user testing** + +Five people attempting a form out loud before it goes live would catch format hint problems and eligibility placement errors in a single afternoon. Informal testing is not optional for government services — it is the cheapest quality check available. + +*GovTech Barbados · alpha.gov.bb · July 2026* From dba9cb8d0636859472109eb4ef4c6a9ae65968fc Mon Sep 17 00:00:00 2001 From: Amoge Date: Thu, 30 Jul 2026 19:45:04 +0100 Subject: [PATCH 2/3] Update plugin.json --- .claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index df36685..73ed4ba 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bimstack", - "version": "0.1.1", + "version": "0.2.0", "description": "Five opinionated specialists for building government digital services in Barbados – anchored to the Barbados Digital Service Standards, the GOV.UK Design Principles, and the GDS Way.", "author": { "name": "GovTech Barbados", From 90a3bae3b86dd48a97498f4ac4a14c69452a1c36 Mon Sep 17 00:00:00 2001 From: Amoge Date: Thu, 30 Jul 2026 19:51:39 +0100 Subject: [PATCH 3/3] Update CHANGELOG.md --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bc4cb75..f820578 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ All notable changes to bimstack will be recorded here. Format inspired by [Keep ### Added +- **A review skill for any citizen-facing service** – `service-design-review` reviews a form, a calculator or estimator, an entry or information page, or a whole journey against the alpha.gov.bb service patterns and the Barbados field standards. Three lenses (content, flow, standards), output triaged into must fix now / fix later / confirm with the MDA / test with users, and it closes by offering the fixes as a comparison prototype rather than a list of notes. Adds `/bimstack:review`. + - **Three field-tested skills from the GovTech Barbados research practice** – `synthesize-research` (raw study data → layered findings package: exec summary, briefing docx, GovTech-style findings deck, and appendix, with a themes sign-off checkpoint before anything is written), `govtech-research-plans` (a complete three-part research plan as one .docx – research plan, discussion guide, note-taking framework – for usability testing, discovery interviews, or concept testing, grounded in the actual prototype being tested), and `service-journey-mapping` (service blueprints and journey maps as self-contained GovBB-style HTML pages with inline commenting, built from a transcript, a Miro board, or an interview with the user). These complement the existing native skills: `research-planning` coaches the thinking behind a discussion guide where `govtech-research-plans` produces the full session document; `journey-map`/`service-blueprint` output canonical Markdown where `service-journey-mapping` produces publishable, commentable HTML - **Four user research skills** – `research-coach` (router and mentor across the whole research cycle, session craft including the false close, direct feedback on the researcher's craft), `research-planning` (decision-linked objectives before any discussion guide, digital literacy warm-up block, behavioural questions over opinion questions, the "if this didn't exist" test), `transcript-analysis` (behaviour over stated preference, workarounds and friction that changed behaviour, cross-referencing prior transcripts as confirms/contradicts/new/extends, coached interpretation), and `research-presenting` (finding → "so what", shared sense-making with the delivery team, action-first readout structure, memorable plain language)