Merged PR 2260: refactor(representations): complete slice-based refactor of representations flow
## Representations Refactor — Behaviour-Preserving Structural Improvements This PR delivers a full refactor of the representations flow, improving structure, readability, and maintainability while preserving all existing behaviour. The work was completed using a controlled, slice-based approach with strict guardrails and regression validation at each step. No changes have been made to user journeys, payloads, routing, or EN/CY behaviour. The result is a cleaner, more maintainable codebase with reduced coupling and clearer separation of concerns, ready for future enhancements without increased risk. --- ## What Was Done The refactor was delivered incrementally across the following slices: - **R1** — Representation entry logic extraction - **R2** — Page loader separation (SSR/data orchestration) - **R3** — Journey step resolution extraction - **R4** — Flow shell decomposition - **R5** — Representation elements normalisation - **R6** — Data/service layer cleanup - **R7** — Summary rendering proof slice - **R8** — Submission/finalisation boundary isolation - **R9** — Summary rollout (Batch 1) Each slice: - was isolated to a single concern - followed strict guardrails - was validated before merge Full detail is available in: `context/representations-refactor-tracker.md` --- ## Key Improvements - Reduced coupling across the representations journey - Separated data loading, orchestration, and rendering concerns - Simplified complex conditional logic into testable helpers - Standardised summary rendering using shared primitives (`SummaryCard`, `SummaryRow`) - Isolated submission/finalisation sequencing into explicit boundaries - Improved overall readability and maintainability --- ## Behaviour Preservation This refactor does **not** change: - User journeys (APP / IP / Agent / LPA) - Route and query behaviour - Payload contracts and API interactions - Redux state shape and usage - Validation rules and messaging - EN/CY behaviour - File upload / PDF / email sequencing - Linked-case logic All changes are structural only. --- ## Validation ### Automated - `npm run lint` — passed (warnings only, no new errors) - `npm run test:reps` — passed (7/7) ### Manual Validated end-to-end across: - APP - IP - Agent - LPA Including: - representation creation - editing/resuming representations - submission flow - confirmation/completion behaviour - summary rendering across case types - EN/CY parity --- ## Risk Management The refactor targeted several high-risk areas: - Case summary entry logic - Representation submission/finalisation sequencing - Dual-mode entry (new vs existing representation) Risk was controlled through: - small, incremental slices - one branch per slice - regression validation per slice - strict behaviour-preservation guardrails - controlled rollout for summary rendering changes --- ## Reviewer Guidance Suggested areas to focus on: - End-to-end representation journey (create → submit → complete) - S...
This commit is contained in:
Robert Bond
@@ -2,15 +2,18 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
This file defines the active working rules for this refactor branch.
|
||||
This file defines the active working rules for the **refactor branch**.
|
||||
|
||||
This branch is focused on **safe, behaviour-preserving refactor of the new appeal flow**.
|
||||
This branch is focused on **safe, behaviour-preserving refactor of portal journeys**, including:
|
||||
|
||||
- New Appeal Flow (completed baseline)
|
||||
- Representations Flow (active refactor stream)
|
||||
|
||||
---
|
||||
|
||||
## Core Rule (Highest Priority)
|
||||
|
||||
Do not change live S78 behaviour unless explicitly instructed.
|
||||
Do not change live behaviour unless explicitly instructed.
|
||||
|
||||
Refactor = improve structure, not behaviour.
|
||||
|
||||
@@ -18,30 +21,62 @@ Refactor = improve structure, not behaviour.
|
||||
|
||||
## Primary Objectives
|
||||
|
||||
1. Make the new appeal flow easier to understand and maintain
|
||||
1. Make core portal journeys easier to understand and maintain
|
||||
2. Reduce risk when making future changes
|
||||
3. Prepare the system for multiple appeal types
|
||||
4. Improve separation of concerns (UI, workflow, data, integrations)
|
||||
3. Improve separation of concerns (UI, workflow, data, integrations)
|
||||
4. Prepare flows for future extensibility (e.g. multiple appeal types, additional journey types)
|
||||
|
||||
---
|
||||
|
||||
## Active Refactor Streams
|
||||
|
||||
### Completed
|
||||
|
||||
- New Appeal Flow (S78)
|
||||
|
||||
### Active
|
||||
|
||||
- Representations Flow
|
||||
|
||||
Each stream must follow **slice-based, behaviour-preserving refactor discipline**.
|
||||
|
||||
---
|
||||
|
||||
## Non-Negotiable Rules
|
||||
|
||||
- Preserve all current user journeys:
|
||||
- start appeal
|
||||
- save and exit
|
||||
- resume appeal
|
||||
- upload documents
|
||||
- check answers
|
||||
- submit appeal
|
||||
- confirmation
|
||||
|
||||
- Do not:
|
||||
- change payload structures
|
||||
- change validation rules
|
||||
- change business logic
|
||||
- hardcode logic that is currently dynamic/config-driven
|
||||
- mix refactor with feature work
|
||||
### Appeals
|
||||
|
||||
- start appeal
|
||||
- save and exit
|
||||
- resume appeal
|
||||
- upload documents
|
||||
- check answers
|
||||
- submit appeal
|
||||
- confirmation
|
||||
|
||||
### Representations
|
||||
|
||||
- start from case summary CTA
|
||||
- select capacity
|
||||
- select representation type
|
||||
- enter content / upload files
|
||||
- check answers
|
||||
- submit representation
|
||||
- completion
|
||||
|
||||
---
|
||||
|
||||
Do not:
|
||||
|
||||
- change payload structures
|
||||
- change validation rules
|
||||
- change business logic
|
||||
- change route/query behaviour
|
||||
- change navigation or side-effect sequencing
|
||||
- introduce EN/CY drift
|
||||
- mix refactor with feature work
|
||||
|
||||
---
|
||||
|
||||
@@ -62,6 +97,41 @@ Always:
|
||||
- Prefer small PRs (<400 LOC where possible)
|
||||
- Avoid large multi-concern changes
|
||||
- Split work into safe slices
|
||||
- One slice = one branch = one commit
|
||||
|
||||
---
|
||||
|
||||
## Branch Model (Critical)
|
||||
|
||||
### Branch Roles
|
||||
|
||||
- `SIPS-Development`
|
||||
- BAU branch
|
||||
- ongoing feature and bugfix work
|
||||
- must remain stable
|
||||
|
||||
- `refactor`
|
||||
- integration branch for refactor work
|
||||
- all refactor slices merge here first
|
||||
|
||||
- feature branches (short-lived)
|
||||
- created from `refactor`
|
||||
- one per slice
|
||||
- merged back into `refactor`
|
||||
|
||||
---
|
||||
|
||||
### Flow
|
||||
|
||||
SIPS-Development
|
||||
↓
|
||||
refactor
|
||||
↓
|
||||
feature/slice-x
|
||||
↓
|
||||
refactor
|
||||
↓ (when stable & validated)
|
||||
SIPS-Development
|
||||
|
||||
---
|
||||
|
||||
@@ -70,30 +140,25 @@ Always:
|
||||
### Default context (only load these):
|
||||
|
||||
- `context/refactor-branch-charter.md`
|
||||
- `context/newappeal-refactor-guardrails.md`
|
||||
- `context/architecture.md`
|
||||
- `context/domain-flows.md`
|
||||
|
||||
### Only load additional context when needed:
|
||||
### Only load when needed:
|
||||
|
||||
- integrations → `integration-map.md`
|
||||
- testing gaps → `test-coverage-map.md`
|
||||
- release concerns → `runbook.md`
|
||||
- specific work plan → `context/plans/*`
|
||||
- appeal work → `newappeal-refactor-guardrails.md`
|
||||
- representation work → `representations-refactor-guardrails.md`
|
||||
- plans → `context/plans/*`
|
||||
|
||||
### Never load by default:
|
||||
|
||||
- all context files
|
||||
- onboarding or overview docs
|
||||
- onboarding docs
|
||||
- all templates
|
||||
- memory-bank contents
|
||||
|
||||
---
|
||||
|
||||
## Templates Usage
|
||||
|
||||
Templates are optional helpers.
|
||||
|
||||
- Use only ONE template when needed
|
||||
- Do not load all templates
|
||||
- Do not treat templates as baseline context
|
||||
@@ -110,25 +175,41 @@ Templates are optional helpers.
|
||||
|
||||
---
|
||||
|
||||
## Testing & Validation Expectations
|
||||
## Regression Safety Rule (Critical)
|
||||
|
||||
Minimum:
|
||||
This is a live system. All refactor work must prove behaviour is unchanged.
|
||||
|
||||
- `npm run lint`
|
||||
- targeted manual verification
|
||||
- EN/CY checks (if user-facing)
|
||||
- negative-path checks (for sensitive flows)
|
||||
Before completing any slice:
|
||||
|
||||
Before changing critical logic:
|
||||
### Appeals
|
||||
|
||||
- add or update regression protection where possible
|
||||
- start appeal
|
||||
- save and exit
|
||||
- resume
|
||||
- upload
|
||||
- check answers
|
||||
- submit
|
||||
- confirmation
|
||||
|
||||
### Representations
|
||||
|
||||
- navigate from case summary → make representation
|
||||
- complete full journey
|
||||
- submit successfully
|
||||
- confirmation shown
|
||||
|
||||
Also:
|
||||
|
||||
- verify EN/CY parity
|
||||
- verify no navigation or state regressions
|
||||
|
||||
If regression cannot be ruled out:
|
||||
→ do not proceed
|
||||
|
||||
---
|
||||
|
||||
## When Unsure
|
||||
|
||||
If any uncertainty exists:
|
||||
|
||||
1. Choose the safest option
|
||||
2. Do not change behaviour
|
||||
3. Call out assumptions
|
||||
@@ -142,87 +223,12 @@ A successful change:
|
||||
|
||||
- preserves behaviour
|
||||
- reduces complexity
|
||||
- improves clarity or structure
|
||||
- improves clarity
|
||||
- is small and safe to merge
|
||||
- does not introduce regression risk
|
||||
- introduces no regression risk
|
||||
|
||||
---
|
||||
|
||||
## One-Line Rule
|
||||
|
||||
If in doubt:
|
||||
|
||||
> Keep behaviour the same, reduce risk, and make the smallest safe change.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Rule (Minimal and Targeted)
|
||||
|
||||
Only document information that is necessary to safely understand or change the system later.
|
||||
|
||||
Document:
|
||||
|
||||
- key decisions (why something was changed)
|
||||
- non-obvious behaviour
|
||||
- risks or constraints (what must not be changed)
|
||||
- important assumptions
|
||||
|
||||
Do not document:
|
||||
|
||||
- obvious code behaviour
|
||||
- step-by-step implementation details
|
||||
- temporary or experimental work
|
||||
- duplicated explanations across files
|
||||
|
||||
Prefer short, focused notes over long explanations.
|
||||
|
||||
If unsure:
|
||||
|
||||
> Will someone break the system in the future if this is not written down?
|
||||
|
||||
If yes → document it
|
||||
If no → do not document it
|
||||
|
||||
Documentation should be minimal, high-signal, and never outweigh the value of the code itself.
|
||||
|
||||
## Branch Safety Rule
|
||||
|
||||
This refactor stream uses the `refactor` branch as its working base branch.
|
||||
|
||||
For refactor work:
|
||||
|
||||
- do all implementation from the `refactor` branch or a short-lived feature branch created from `refactor`
|
||||
- do not implement refactor work directly on `SIPS-Development`
|
||||
|
||||
`SIPS-Development` remains the BAU integration branch.
|
||||
Refactor changes may be merged into `SIPS-Development` only when proven safe.
|
||||
|
||||
If branch context is unclear, stop and confirm before making changes.
|
||||
|
||||
## Branch Model
|
||||
|
||||
- `SIPS-Development` = BAU branch
|
||||
- `refactor` = refactor integration branch
|
||||
- optional short-lived working branches for individual slices should be created from `refactor`
|
||||
|
||||
## Regression Safety Rule (Critical)
|
||||
|
||||
This is a live system. All refactor work must prove behaviour is unchanged.
|
||||
|
||||
Before completing any slice:
|
||||
|
||||
- verify core journey behaviour has not changed
|
||||
- verify protected flows still work:
|
||||
- save and exit
|
||||
- resume appeal
|
||||
- upload documents
|
||||
- check answers
|
||||
- submit appeal
|
||||
- confirmation
|
||||
|
||||
- verify EN/CY parity for any affected areas
|
||||
|
||||
A slice is NOT complete until regression behaviour is confirmed.
|
||||
|
||||
If regression cannot be confidently ruled out:
|
||||
→ do not proceed to next slice
|
||||
|
||||
Reference in New Issue
Block a user