pedwfrontend/.clinerules/CONTRIBUTING_AI.md

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.