Robert Bond
ecd6075c3a
Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590, #22591
138 lines
2.8 KiB
Markdown
138 lines
2.8 KiB
Markdown
# 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.
|