pedwfrontend/context/newappeal-factor-guardrails.md

New Appeal Refactor Guardrails

Purpose

These guardrails apply to all AI-assisted and human-assisted work on the refactor branch for the new appeal flow.

Critical Rule

Preserve the current live S78 behaviour unless the task explicitly requires a behaviour change.

Do not assume a cleaner implementation is allowed to alter behaviour.

Protected Areas

Treat the following as protected flow files:

• pages/newappeal/index.js
• pages/newappeal/[appealtypes].js
• components/newappeal/buildsection.js
• components/newappeal/buildchecksection.js
• components/newappeal/buildrow.js
• components/newappeal/buildfield.js
• components/newappeal/buildcheckrow.js
• components/newappeal/complete.js
• components/newappeal/aboutyou.js
• components/newappeal/createCase.js
• any helpers or service modules used directly by save/progress/upload/submit/finalise logic

Protected Behaviour

The following must not regress:

1. Start a new S78 appeal
2. Create case / initial journey entry
3. Section rendering from form definition
4. Section progression
5. Save and exit
6. Resume saved appeal
7. File/document upload behaviour
8. Check answers page
9. Appeal PDF generation/download path
10. Final submit/finalisation
11. Confirmation page behaviour
12. Email/notification side effects
13. English/Welsh parity for touched areas

Required Refactor Approach

When refactoring:

1. Understand current behaviour first
2. Identify the smallest safe boundary
3. Prefer extraction of pure/helper logic
4. Keep public interfaces stable where possible
5. Avoid changing UI, business rules, and structure in one step
6. Keep each slice easy to review and revert

Required Testing Mindset

Before changing critical flow behaviour, add or update protection such as:

• characterization tests for current behaviour
• targeted integration/service tests
• journey-level regression checks
• payload-shape assertions for save/submit/finalise paths

If automation is not practical yet, include an explicit manual verification matrix.

Payload/Integration Safety

Do not change without explicit need:

• CRM payload field names or structure
• boolean/value normalization behaviour
• document/file metadata shape
• save/resume payload expectations
• PDF generation inputs
• notification template selection or personalisation structure

i18n / Accessibility Safety

For touched user-facing behaviour:

• keep EN/CY behaviour aligned
• keep labels, messages, and route behaviour consistent
• preserve semantic structure, focus behaviour, and validation messaging

Delivery Safety

Preferred pattern for each change:

1. protect current behaviour
2. extract one concern
3. run focused validation
4. keep rollback straightforward
5. merge only when safe

What To Avoid

Do not:

• perform broad rewrites
• mix feature delivery with refactor work
• replace dynamic/config-driven logic with one-off hardcoding
• move many responsibilities at once
• introduce new dependencies unless clearly justified
• silently change business rules while “cleaning up”

Refactor Success Criteria

A refactor slice is successful when it:

• preserves behaviour
• reduces complexity or coupling
• improves readability or testability
• keeps regression risk controlled
• remains small enough to merge safely into SIPS-Development