Robert Bond
ecd6075c3a
Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590, #22591
2.8 KiB
2.8 KiB
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:
- Enter case summary page
- Click Make representation / consultation
- Navigate to representation flow
- Select capacity
- Select representation type
- Enter content and upload files
- View check answers
- Submit representation
- 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:
- Understand current behaviour first
- Identify smallest safe boundary
- Prefer extraction over rewrite
- Keep interfaces stable
- Avoid mixing concerns in one change
- 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.