# Contributing with AI (Refactor Branch — PEDW FrontEnd)

## Purpose

This guide defines how engineers and AI agents should work safely and efficiently in this refactor branch.

This branch focuses on **safe, behaviour-preserving refactor of the new appeal flow**.

---

## Start Here (Required Order)

1. Read `.clinerules/refactor-branch-rules.md`
2. Read `GUARDRAILS.md`
3. Read core context:
    - `context/refactor-branch-charter.md`
    - `context/newappeal-refactor-guardrails.md`
    - `context/architecture.md`
    - `context/domain-flows.md`

Only read additional files when directly relevant.

Do **not** load all context, templates, or memory-bank files by default.

---

## Core Principle

This is a **refactor branch**, not a feature branch.

- Preserve current live S78 behaviour
- Do not introduce business-rule changes unless explicitly requested
- Prefer small, safe, reversible changes
- Focus on structure, not behaviour

---

## Standard AI-Assisted Workflow

### 1. Scope

- Define requirement
- Confirm non-goals
- Identify impacted flow areas
- Identify risk level

### 2. Plan

- Keep plan small and incremental
- Identify safe boundaries
- Avoid mixing refactor + feature work

### 3. Implement

- Make the smallest viable change
- Prefer extraction over rewrite
- Preserve interfaces and payload shapes

### 4. Validate

Minimum required:

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

### 5. Document (only when needed)

- update `memory-bank/change-log.md` for non-trivial work
- record decisions or pitfalls if useful

---

## Templates (Use Only When Needed)

Templates are optional tools, not default context.

Use **only one** template if needed:

- feature implementation
- bug fix
- refactor
- debugging
- code review

Do not load all templates.
Do not treat templates as baseline context.

---

## Context Loading Rule (Critical)

Always use the **minimum required context**.

### Default context for this branch:

- `context/refactor-branch-charter.md`
- `context/newappeal-refactor-guardrails.md`
- `context/architecture.md`
- `context/domain-flows.md`

### Only load additional files when:

- working with integrations → `integration-map.md`
- reviewing test gaps → `test-coverage-map.md`
- performing release work → `runbook.md`
- working on specific planned sequence → `context/plans/*`

Never load:

- all context files
- all templates
- onboarding or overview docs

---

## Branching Protocol

This repository currently uses different branch rules depending on the work type.

### For BAU / normal delivery work

- create work branches from `SIPS-Development`

### For new appeal refactor work

- use the `refactor` branch as the base branch
- do refactor implementation either:
    - directly on `refactor`, if that is the agreed working model, or
    - on a short-lived feature branch created from `refactor`

Do not perform refactor implementation directly on `SIPS-Development`.

If unsure which branch model applies, stop and confirm before making changes.

---

## No-Break Rules (Always Enforce)

- Do not weaken auth/session behaviour
- Do not weaken security headers/CSP
- Keep EN/CY behaviour aligned
- Do not expose secrets or personal data
- Protect save/resume/upload/submit journeys

---

## PR Minimum (AI-Assisted)

Every change must include:

- Scope summary
- Files changed
- Risk notes (auth/data/i18n/a11y)
- Validation evidence
- Rollback plan

---

## Handling Unknowns

If unsure:

1. Choose the safer option
2. Do not change behaviour
3. call out assumptions clearly
4. log open questions if needed

---

## Summary Rule

If in doubt:

> Preserve behaviour, reduce risk, keep changes small.