pedwfrontend/.clinerules/refactor-branch-rules.md

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.