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

Refactor Branch Rules (Active)

Purpose

This file defines the active working rules for this refactor branch.

This branch is focused on safe, behaviour-preserving refactor of the new appeal flow.

---

Core Rule (Highest Priority)

Do not change live S78 behaviour unless explicitly instructed.

Refactor = improve structure, not behaviour.

---

Primary Objectives

1. Make the new appeal flow 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)

---

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

---

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

---

Context Usage Rules (Critical for Efficiency)

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:

• integrations → integration-map.md
• testing gaps → test-coverage-map.md
• release concerns → runbook.md
• specific work plan → context/plans/*

Never load by default:

• all context files
• onboarding or overview 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

---

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

---

Testing & Validation Expectations

Minimum:

• npm run lint
• targeted manual verification
• EN/CY checks (if user-facing)
• negative-path checks (for sensitive flows)

Before changing critical logic:

• add or update regression protection where possible

---

When Unsure

If any uncertainty exists:

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 or structure
• is small and safe to merge
• does not introduce 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