Robert Bond
37a81522d5
## 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...
4.1 KiB
4.1 KiB
Refactor Branch Rules (Active)
Purpose
This file defines the active working rules for the refactor branch.
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 behaviour unless explicitly instructed.
Refactor = improve structure, not behaviour.
Primary Objectives
- Make core portal journeys easier to understand and maintain
- Reduce risk when making future changes
- Improve separation of concerns (UI, workflow, data, integrations)
- 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:
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
Refactor Approach
Always:
- Understand current behaviour first
- Identify smallest safe change
- Prefer extraction over rewrite
- Keep public interfaces stable
- Make changes easy to review and revert
Change Size Guidance
- 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
- created from
Flow
SIPS-Development ↓ refactor ↓ feature/slice-x ↓ refactor ↓ (when stable & validated) SIPS-Development
Context Usage Rules (Critical for Efficiency)
Default context (only load these):
context/refactor-branch-charter.mdcontext/architecture.mdcontext/domain-flows.md
Only load when needed:
- appeal work →
newappeal-refactor-guardrails.md - representation work →
representations-refactor-guardrails.md - plans →
context/plans/*
Never load by default:
- all context files
- onboarding docs
- all templates
Templates Usage
- Use only ONE template when needed
- Do not load all templates
- Do not treat templates as baseline context
Safety Rules
- Do not weaken authentication or session logic
- Do not weaken security headers or middleware
- Do not expose secrets or personal data
- Preserve EN/CY parity
- Maintain accessibility standards
Regression Safety Rule (Critical)
This is a live system. All refactor work must prove behaviour is unchanged.
Before completing any slice:
Appeals
- 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
- Choose the safest option
- Do not change behaviour
- Call out assumptions
- Keep the change minimal
Definition of Success
A successful change:
- preserves behaviour
- reduces complexity
- improves clarity
- is small and safe to merge
- introduces no regression risk
One-Line Rule
Keep behaviour the same, reduce risk, and make the smallest safe change.