Merged PR 2246: refactor reps first slice

Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590, #22591
2026-04-15 09:28:50 +00:00
parent 15c35d201e
commit ecd6075c3a
9 changed files with 1520 additions and 371 deletions
@@ -0,0 +1,137 @@
+# Representations Refactor Guardrails
+
+## Purpose
+
+These guardrails apply to all work on the **representations refactor stream**.
+
+This stream follows the same discipline as the new appeal refactor:
+
+> Behaviour-preserving, slice-based refactor of a live journey.
+
+---
+
+## Critical Rule
+
+Preserve the current live behaviour of the representations journey.
+
+Do not assume a cleaner implementation allows behaviour changes.
+
+---
+
+## Protected Journey
+
+The following user journey must not regress:
+
+1. Enter case summary page
+2. Click **Make representation / consultation**
+3. Navigate to representation flow
+4. Select capacity
+5. Select representation type
+6. Enter content and upload files
+7. View check answers
+8. Submit representation
+9. View completion/confirmation
+
+---
+
+## Protected Behaviour
+
+Do not change:
+
+- representation eligibility logic (dates, appeal type, specialist process)
+- CTA visibility and routing from case summary
+- capacity selection behaviour
+- representation type branching
+- validation rules and messaging
+- payload shape sent to backend/CRM
+- file upload handling and metadata
+- submission/finalisation flow
+- confirmation behaviour
+- navigation order or step progression
+- route/query parameters
+- EN/CY behaviour
+
+---
+
+## Refactor Approach
+
+When refactoring:
+
+1. Understand current behaviour first
+2. Identify smallest safe boundary
+3. Prefer extraction over rewrite
+4. Keep interfaces stable
+5. Avoid mixing concerns in one change
+6. Keep slices small and reversible
+
+---
+
+## Required Testing Mindset
+
+Before completing any slice:
+
+- manually walk the full representation journey
+- verify:
+    - start from case summary CTA
+    - capacity → type → content → check → submit
+    - successful completion
+- verify EN/CY parity
+- verify no navigation or state regression
+
+If behaviour cannot be confidently verified:
+→ do not proceed
+
+---
+
+## Payload / Integration Safety
+
+Do not change without explicit requirement:
+
+- CRM payload structure
+- field names or mapping
+- document/file metadata shape
+- blob storage structure
+- submission API behaviour
+
+---
+
+## i18n / Accessibility Safety
+
+For any user-facing change:
+
+- maintain EN/CY parity
+- do not change translation keys unless required
+- preserve accessibility semantics and structure
+- maintain focus and validation behaviour
+
+---
+
+## What To Avoid
+
+Do not:
+
+- rewrite large components in one step
+- introduce new business rules
+- hardcode dynamic logic
+- mix refactor with feature work
+- change multiple concerns in one slice
+
+---
+
+## Refactor Success Criteria
+
+A slice is successful when:
+
+- behaviour is unchanged
+- complexity is reduced
+- readability is improved
+- regression risk is controlled
+- change is small and reviewable
+
+---
+
+## One-Line Rule
+
+If in doubt:
+
+> Keep behaviour the same, reduce risk, and make the smallest safe change.