Robert Bond
ecd6075c3a
Related work items: #22570, #22576, #22577, #22583, #22586, #22587, #22588, #22590, #22591
235 lines
4.1 KiB
Markdown
235 lines
4.1 KiB
Markdown
# 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
|
|
|
|
1. Make core portal journeys easier to understand and maintain
|
|
2. Reduce risk when making future changes
|
|
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:
|
|
|
|
### 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:
|
|
|
|
1. Understand current behaviour first
|
|
2. Identify smallest safe change
|
|
3. Prefer extraction over rewrite
|
|
4. Keep public interfaces stable
|
|
5. 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`
|
|
|
|
---
|
|
|
|
### 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.md`
|
|
- `context/architecture.md`
|
|
- `context/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
|
|
|
|
1. Choose the safest option
|
|
2. Do not change behaviour
|
|
3. Call out assumptions
|
|
4. 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.
|