177 lines
3.7 KiB
Markdown
177 lines
3.7 KiB
Markdown
# 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.
|