Merged PR 2401: docs: document representation participation availability model
docs: document representation participation availability model Related work items: #23754
This commit is contained in:
Robert Bond
@@ -15,6 +15,11 @@ PEDW is in a **late-stage refactor stabilization** phase.
|
||||
- New Appeal slice stream documented complete (`context/refactor-tracker.md`, `context/newappeal-refactor-current-state.md`).
|
||||
- Significant route/breadcrumb decomposition and helper extraction completed.
|
||||
- Broad endpoint contract hardening completed across key clusters.
|
||||
- Representation Participation Availability investigation completed from a technical discovery/documentation perspective.
|
||||
- Representation participation behaviour is now documented as one coherent decision model with layered appeal-type, specialist-process, participant-type, consultation, and date-window exceptions.
|
||||
- Source documents added:
|
||||
- `docs/representation-participation-availability.md` (developers / architects / maintainers)
|
||||
- `docs/representation-participation-business-review.md` (business / product / SME validation)
|
||||
|
||||
## What is incomplete
|
||||
|
||||
@@ -22,6 +27,7 @@ PEDW is in a **late-stage refactor stabilization** phase.
|
||||
- SSR loader resilience normalization across myportal/representation/new appeal.
|
||||
- Logging hardening consistency in auth/file/account-sensitive paths.
|
||||
- Remaining decomposition hotspots (`components/elements/index.js`, representation flow internals).
|
||||
- Business validation of Representation Participation Availability before any further representation-policy adoption, expansion, or behaviour-change work.
|
||||
|
||||
## Operational risk profile (current)
|
||||
|
||||
@@ -36,3 +42,17 @@ Top active risks:
|
||||
|
||||
- Some context docs still describe pre-refactor representation baseline; treat those as historical unless updated by active slice evidence.
|
||||
- Legacy commented code remains in active files (especially journey files) and should be treated as cleanup debt, not source-of-truth runtime behaviour.
|
||||
|
||||
## Representation Participation Availability — Current State
|
||||
|
||||
- Technical discovery/documentation stream is complete.
|
||||
- Current architectural conclusion: do **not** continue searching for a new representation domain boundary at this point.
|
||||
- Representation participation is best understood as one coherent decision model with layered exceptions rather than a set of unrelated CTA rules.
|
||||
- Known divergences and compatibility-sensitive behaviours are documented and should be preserved unless an explicit business decision authorizes change.
|
||||
- Current state: awaiting business validation of `docs/representation-participation-business-review.md` before any further representation-policy adoption, expansion, or behavioural change work.
|
||||
|
||||
## Next likely discovery candidate
|
||||
|
||||
- **Case Lifecycle / Status Decision Model Discovery**
|
||||
- Investigate how the portal interprets case progress, stages, statuses, closed states, dashboard grouping, and user-facing lifecycle messaging.
|
||||
- Treat this as discovery only until the new representation participation documentation has been reviewed and business validation feedback is available.
|
||||
|
||||
@@ -0,0 +1,593 @@
|
||||
# Representation Participation Availability
|
||||
|
||||
## Purpose
|
||||
|
||||
This document records the current live **Representation Participation Availability** model used by the PEDW portal.
|
||||
|
||||
It is intended to preserve knowledge established through characterization and discovery work so that future developers, architects, and maintainers do not need to repeat the same investigations.
|
||||
|
||||
This document is based on observed current behaviour across the live decision paths, including:
|
||||
|
||||
- `lib/domain/representation-policy/*`
|
||||
- `components/case/summary/utils/representationEntry.js`
|
||||
- `components/search/repsonresults.js`
|
||||
- existing characterization documentation and tests
|
||||
|
||||
This is a **behaviour characterization document**, not a redesign proposal.
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Current portal behaviour appears to be making one broad business decision:
|
||||
|
||||
> Can this participant engage in representation or consultation activity for this case right now?
|
||||
|
||||
The current system does not behave like a set of unrelated button rules.
|
||||
|
||||
Instead, it behaves like a broadly coherent participation-availability policy with layered exceptions based on:
|
||||
|
||||
- appeal type
|
||||
- specialist process
|
||||
- participant type
|
||||
- date-window state
|
||||
- consultation state
|
||||
- CRM field availability/variants
|
||||
|
||||
The policy has evolved organically over time.
|
||||
|
||||
As a result, some behaviours are clearly structured and repeatable, while others are compatibility-sensitive and exception-driven. A small number of current divergences between consumers appear historical rather than explicitly modelled, but they are now characterized and must be treated as preserved live behaviour unless a deliberate business change is approved.
|
||||
|
||||
---
|
||||
|
||||
## Core Business Decision
|
||||
|
||||
The decision being made is:
|
||||
|
||||
> Can this participant engage in representation or consultation activity for this case right now?
|
||||
|
||||
This is broader than a simple CTA visibility question.
|
||||
|
||||
In practice, the live system decides a combination of:
|
||||
|
||||
- whether participation is available at all
|
||||
- whether the relevant participation window is open
|
||||
- whether an exception applies for the case/process/participant combination
|
||||
- whether unavailable-state messaging should be shown, suppressed, or rendered differently
|
||||
- whether the case is currently handled as a consultation rather than a representation
|
||||
|
||||
This means the model should be understood as a **participation-availability decision**, not merely a rendering decision.
|
||||
|
||||
---
|
||||
|
||||
## Decision Inputs
|
||||
|
||||
The following inputs have been confirmed to affect the current live decision.
|
||||
|
||||
### 1. Appeal type
|
||||
|
||||
**Purpose**
|
||||
|
||||
Appeal type is the main top-level discriminator for participation behaviour.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- determines whether the case is excluded entirely
|
||||
- determines whether appeal-type-specific rules apply
|
||||
- determines whether Householder, CPO, ROW, Advert, or consultation-specific logic is used
|
||||
- affects which date fields are relevant in some branches
|
||||
|
||||
### 2. Appeal type family
|
||||
|
||||
**Purpose**
|
||||
|
||||
Appeal type family is used for broad exclusion rules.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- certain families are blocked from representation participation regardless of other conditions
|
||||
- explicit excluded appeal type IDs are also blocked even where family grouping might otherwise allow them
|
||||
|
||||
Current excluded families/IDs are characterized through `canShowRepresentationButtonForAppealType(...)`.
|
||||
|
||||
### 3. Specialist process
|
||||
|
||||
**Purpose**
|
||||
|
||||
Specialist process acts as an overlay for certain appeal types, especially ROW and Advert.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- determines whether ROW is treated as hearing vs non-hearing
|
||||
- determines whether Advert is treated as written reps, hearing, or other
|
||||
- can change whether date gating applies
|
||||
- can change whether participation is allowed, blocked, or permissively allowed by fallback
|
||||
|
||||
### 4. Participant type
|
||||
|
||||
**Purpose**
|
||||
|
||||
Some participation rules depend on who the actor is.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- Householder is LPA-only
|
||||
- Advert written reps is LPA-only
|
||||
- non-LPA Householder unavailable state also triggers message suppression
|
||||
|
||||
### 5. Representation window
|
||||
|
||||
**Purpose**
|
||||
|
||||
For general cases, participation depends on whether the current representation period is open.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- controls whether general participation is available
|
||||
- controls blocked/ended-state behaviour for many cases
|
||||
- uses field fallbacks in general resolution logic, but not all appeal-type exceptions use those fallbacks
|
||||
|
||||
### 6. Consultation window
|
||||
|
||||
**Purpose**
|
||||
|
||||
Some participation is treated as consultation activity rather than general representation activity.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- consultation routes are controlled by consultation open/close dates
|
||||
- consultation behaviour is separate from the general representation window path
|
||||
|
||||
### 7. Date state
|
||||
|
||||
**Purpose**
|
||||
|
||||
The system distinguishes between currently open, expired, future, and incomplete/missing windows.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- open windows allow participation where no other exception blocks it
|
||||
- expired windows block date-gated participation
|
||||
- future windows also block date-gated participation
|
||||
- missing/incomplete dates currently block some date-gated paths
|
||||
|
||||
### 8. CRM compatibility variants
|
||||
|
||||
**Purpose**
|
||||
|
||||
Historic CRM field variants are part of the live contract.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- different consumers can reach different results depending on which field variant is present
|
||||
- canonical vs misspelled specialist-process fields are especially important for ROW and Advert
|
||||
- start-date and due-date variants can change participation availability when specific branches do not use the broader fallbacks
|
||||
|
||||
### 9. Field presence / absence
|
||||
|
||||
**Purpose**
|
||||
|
||||
Some branches make permissive decisions when data is absent; others make blocking decisions.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- missing ROW specialist-process data currently falls through to allowed behaviour
|
||||
- missing Advert specialist-process data currently falls through to blocked behaviour
|
||||
- missing date data blocks CPO and ROW hearing paths
|
||||
|
||||
### 10. String vs numeric appeal type handling
|
||||
|
||||
**Purpose**
|
||||
|
||||
Appeal type format affects which special-case branch executes.
|
||||
|
||||
**Effect on decision**
|
||||
|
||||
- some helper paths coerce string values safely
|
||||
- some consumer `switch` branches depend on numeric values and can be bypassed by string input
|
||||
- this is characterized live behaviour and must be preserved unless intentionally changed
|
||||
|
||||
---
|
||||
|
||||
## Rule Catalogue
|
||||
|
||||
## Core Rules
|
||||
|
||||
### Excluded appeal categories
|
||||
|
||||
Participation is blocked entirely for the currently excluded appeal-type families:
|
||||
|
||||
- `ELECTRICITY_ACT`
|
||||
- `TRANSPORT_WORKS`
|
||||
- `HARBOUR_REVISION_ORDER`
|
||||
- `WAYLEAVE`
|
||||
- `NON_VALIDATION`
|
||||
|
||||
Participation is also blocked for explicit excluded appeal type IDs:
|
||||
|
||||
- `846040020`
|
||||
- `846040023`
|
||||
|
||||
### General participation window model
|
||||
|
||||
For most non-excluded cases:
|
||||
|
||||
- participation is generally available
|
||||
- participation depends on the relevant window being open
|
||||
- once the period is no longer open, participation becomes unavailable
|
||||
|
||||
The general representation-window resolver currently uses:
|
||||
|
||||
- start: `pinswg_startdate` or `pinswg_startdates` or `pinswg_applicationacceptedasvalid`
|
||||
- end: `pinswg_finalcommentsduedate` or `pinswg_endofrepresentationperiod`
|
||||
|
||||
### Permissive default model
|
||||
|
||||
For many non-special cases, once broad exclusion rules are passed, behaviour is permissive unless a specific exception blocks participation.
|
||||
|
||||
This permissive model is important in explaining current ROW non-hearing and missing-data fallbacks.
|
||||
|
||||
---
|
||||
|
||||
## Appeal-Type Exceptions
|
||||
|
||||
### Householder
|
||||
|
||||
Current live behaviour:
|
||||
|
||||
- participation is LPA-only
|
||||
- non-LPA actors are blocked
|
||||
- blocked explanatory messaging is suppressed for non-LPA Householder users
|
||||
|
||||
### CPO
|
||||
|
||||
Current live behaviour:
|
||||
|
||||
- participation is controlled by a CPO-specific date window
|
||||
- the CPO rule uses `pinswg_startdate` → `pinswg_statementduedate`
|
||||
- it does not broaden to general start-date fallbacks
|
||||
- missing, future, or expired window values block participation
|
||||
|
||||
### ROW
|
||||
|
||||
Current live behaviour:
|
||||
|
||||
- hearing specialist process is date-gated
|
||||
- non-hearing specialist process values are generally allowed
|
||||
- missing specialist-process information currently falls through to permissive behaviour
|
||||
- only `pinswg_startdate` and `pinswg_finalcommentsduedate` are used for hearing date gating
|
||||
|
||||
### Advert
|
||||
|
||||
Current live behaviour:
|
||||
|
||||
- written reps is LPA-only
|
||||
- hearing is allowed for LPA and non-LPA
|
||||
- other specialist-process values are blocked
|
||||
- Advert is not currently date-gated
|
||||
|
||||
### Consultation participation
|
||||
|
||||
Current live behaviour:
|
||||
|
||||
- consultation participation is handled separately from general representation participation
|
||||
- consultation availability depends on consultation open/close dates
|
||||
|
||||
---
|
||||
|
||||
## Specialist Process Overlays
|
||||
|
||||
### Hearing
|
||||
|
||||
- ROW hearing is date-gated
|
||||
- Advert hearing is allowed and not date-gated
|
||||
|
||||
### Written reps
|
||||
|
||||
- Advert written reps is LPA-only
|
||||
|
||||
### Other process-specific restrictions
|
||||
|
||||
- ROW non-hearing remains permissive
|
||||
- Advert non-allowlisted specialist-process values are blocked
|
||||
|
||||
---
|
||||
|
||||
## Participant-Type Overlays
|
||||
|
||||
### LPA-only behaviour
|
||||
|
||||
Confirmed current LPA-only participation rules:
|
||||
|
||||
- Householder participation
|
||||
- Advert written reps participation
|
||||
|
||||
### Non-LPA suppression behaviour
|
||||
|
||||
Confirmed current suppression rule:
|
||||
|
||||
- non-LPA Householder users receive neither CTA nor blocked explanatory message
|
||||
|
||||
---
|
||||
|
||||
## Unavailable-State Behaviour
|
||||
|
||||
Current unavailable-state handling is part of the decision model.
|
||||
|
||||
### Blocked messaging
|
||||
|
||||
When a participation branch is in scope and the relevant path is unavailable, the portal may show blocked explanatory text.
|
||||
|
||||
### Ended-period messaging
|
||||
|
||||
Some consumers also render period-ended messaging once a participation period is considered closed.
|
||||
|
||||
### Suppression rules
|
||||
|
||||
Blocked messaging is currently suppressed for non-LPA Householder users.
|
||||
|
||||
### Important note
|
||||
|
||||
Unavailable-state rendering is not fully centralized. This contributes to a small number of current compatibility-sensitive differences in how blocked and ended states are expressed.
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree
|
||||
|
||||
The current live decision can be reconstructed at a business-logic level as follows.
|
||||
|
||||
1. **Is this appeal type excluded from representation participation?**
|
||||
- If yes → participation unavailable.
|
||||
- If no → continue.
|
||||
|
||||
2. **Is this case currently being handled as a consultation route?**
|
||||
- If yes → use consultation availability rules based on consultation dates.
|
||||
- If no → continue with general representation availability.
|
||||
|
||||
3. **Is the general participation route in scope and is the relevant window open?**
|
||||
- If no → participation unavailable or ended-state behaviour may apply.
|
||||
- If yes → continue.
|
||||
|
||||
4. **Does this appeal type have a specific exception rule?**
|
||||
- Householder → allow only LPA.
|
||||
- CPO → allow only if CPO window (`startdate` → `statementduedate`) is open.
|
||||
- ROW → use specialist-process overlay.
|
||||
- Advert → use specialist-process overlay.
|
||||
- Other types → permissive allow.
|
||||
|
||||
5. **If specialist process is relevant, what process applies?**
|
||||
- ROW hearing → date-gated.
|
||||
- ROW non-hearing → allowed.
|
||||
- Advert written reps → LPA-only.
|
||||
- Advert hearing → allowed.
|
||||
- Advert other values → blocked.
|
||||
|
||||
6. **If participation is unavailable, should unavailable-state messaging be shown or suppressed?**
|
||||
- non-LPA Householder → suppress blocked message.
|
||||
- otherwise → blocked and/or ended messaging may be shown depending on consumer and date state.
|
||||
|
||||
This decision tree describes the live logic conceptually. It does not imply that the current implementation is centralized.
|
||||
|
||||
---
|
||||
|
||||
## Behaviour Matrix Summary
|
||||
|
||||
This section intentionally summarizes the characterized matrix rather than reproducing every row.
|
||||
|
||||
| Scenario | Current summarized behaviour |
|
||||
| -------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| General cases | Participation generally available while the relevant representation window is open |
|
||||
| Excluded categories | Participation unavailable regardless of other conditions |
|
||||
| Householder | LPA-only participation; non-LPA blocked; blocked message suppressed for non-LPA |
|
||||
| CPO | Participation date-gated using a CPO-specific due date |
|
||||
| ROW hearing | Participation allowed only while the ROW hearing window is open |
|
||||
| ROW non-hearing | Participation generally available |
|
||||
| Advert written reps | LPA-only participation |
|
||||
| Advert hearing | Participation available for LPA and non-LPA |
|
||||
| Advert other process types | Participation unavailable |
|
||||
| Consultation participation | Controlled separately by consultation dates |
|
||||
|
||||
For the full characterization detail, maintainers should refer back to the investigation outputs and phase22 tests.
|
||||
|
||||
---
|
||||
|
||||
## Known Compatibility Constraints
|
||||
|
||||
### CRM Field Variants
|
||||
|
||||
The following are confirmed compatibility-sensitive inputs and must be preserved as live contract.
|
||||
|
||||
#### Specialist-process variants
|
||||
|
||||
- `pinswg_specialistcaseprocess`
|
||||
- `pinswg_speacialistcaseprocess`
|
||||
|
||||
These are not interchangeable in current live behaviour.
|
||||
|
||||
#### Start-date variants
|
||||
|
||||
- `pinswg_startdate`
|
||||
- `pinswg_startdates`
|
||||
- `pinswg_applicationacceptedasvalid`
|
||||
|
||||
These are used differently across general vs exception-specific paths.
|
||||
|
||||
#### Due-date variants
|
||||
|
||||
- `pinswg_statementduedate`
|
||||
- `pinswg_finalcommentsduedate`
|
||||
- `pinswg_endofrepresentationperiod`
|
||||
|
||||
These are not uniformly applied across all consumers and exception paths.
|
||||
|
||||
These variants are compatibility requirements, not cleanup targets.
|
||||
|
||||
### String vs Numeric Appeal Types
|
||||
|
||||
Current behaviour is format-sensitive.
|
||||
|
||||
- some top-level exclusions still apply because helper logic coerces numeric values
|
||||
- some appeal-type-specific branches depend on numeric `switch` matching
|
||||
- as a result, string values such as `"846040015"` or `"846040018"` can bypass special-case logic and fall through to permissive behaviour
|
||||
|
||||
This behaviour is characterized and must not be changed accidentally.
|
||||
|
||||
### Preserved Consumer Divergence
|
||||
|
||||
Current live behaviour is not fully standardized across consumers.
|
||||
|
||||
Known divergence currently exists between:
|
||||
|
||||
- case summary behaviour
|
||||
- search-results behaviour
|
||||
- extracted domain helpers
|
||||
|
||||
These differences must be treated as preserved live behaviour unless an explicit business decision authorizes standardization.
|
||||
|
||||
---
|
||||
|
||||
## Known Divergences
|
||||
|
||||
### 1. ROW misspelled specialist-process behaviour
|
||||
|
||||
**Observed behaviour**
|
||||
|
||||
- summary uses only `pinswg_specialistcaseprocess` for ROW
|
||||
- search uses normalized fallback across canonical + misspelled fields
|
||||
- where only the misspelled field is present with hearing value, summary can allow participation while search date-gates/block it
|
||||
|
||||
**Why it matters**
|
||||
|
||||
The same underlying case can appear available in one portal area and unavailable in another.
|
||||
|
||||
**Status**
|
||||
|
||||
Characterized and preserved.
|
||||
|
||||
### 2. Advert canonical vs misspelled specialist-process behaviour
|
||||
|
||||
**Observed behaviour**
|
||||
|
||||
- summary reads only `pinswg_speacialistcaseprocess`
|
||||
- search uses canonical-first normalization
|
||||
- canonical-only field population can block summary while allowing search
|
||||
|
||||
**Why it matters**
|
||||
|
||||
Portal behaviour depends on which CRM field variant is populated.
|
||||
|
||||
**Status**
|
||||
|
||||
Characterized and preserved.
|
||||
|
||||
### 3. Conflicting field precedence for Advert
|
||||
|
||||
**Observed behaviour**
|
||||
|
||||
- when both canonical and misspelled specialist-process fields exist with different values, summary uses the misspelled field directly
|
||||
- search gives precedence to the canonical field
|
||||
|
||||
**Why it matters**
|
||||
|
||||
Conflicting field values produce deterministic user-facing divergence.
|
||||
|
||||
**Status**
|
||||
|
||||
Characterized and preserved.
|
||||
|
||||
### 4. CPO ended-message behaviour
|
||||
|
||||
**Observed behaviour**
|
||||
|
||||
- CPO participation gating uses `pinswg_statementduedate`
|
||||
- blocked-state date display also uses the CPO due date
|
||||
- ended-message closure checks still rely on general ended-period logic using `pinswg_finalcommentsduedate`
|
||||
|
||||
**Why it matters**
|
||||
|
||||
Participation can be blocked using one deadline while ended-period messaging is determined differently.
|
||||
|
||||
**Status**
|
||||
|
||||
Characterized; business intent still needs validation.
|
||||
|
||||
---
|
||||
|
||||
## Characterization Coverage
|
||||
|
||||
### Existing characterization tests
|
||||
|
||||
The repository already contains phase22 characterization tests covering key areas of this behaviour, including:
|
||||
|
||||
- `tests/phase22/representation-row-entry-rule.test.cjs`
|
||||
- `tests/phase22/representation-advert-entry-rule.test.cjs`
|
||||
- `tests/phase22/representation-cpo-entry-rule.test.cjs`
|
||||
|
||||
### Behaviour currently protected by tests
|
||||
|
||||
Existing tests cover, among other things:
|
||||
|
||||
- ROW hearing date gating
|
||||
- ROW non-hearing permissive behaviour
|
||||
- ROW canonical vs misspelled specialist-process divergence
|
||||
- ROW string appeal-type bypass behaviour
|
||||
- Advert written reps LPA-only behaviour
|
||||
- Advert hearing availability
|
||||
- Advert blocking for other process values
|
||||
- Advert canonical vs misspelled divergence
|
||||
- Advert conflicting precedence divergence
|
||||
- Advert string appeal-type bypass behaviour
|
||||
- CPO open / future / expired / missing date behaviour
|
||||
- CPO refusal to broaden to fallback start fields
|
||||
|
||||
### Behaviour still requiring additional validation
|
||||
|
||||
The following remain especially valuable for ongoing protection:
|
||||
|
||||
- summary vs search unavailable-state rendering differences
|
||||
- Householder blocked-message suppression
|
||||
- consultation availability behaviour
|
||||
- CPO ended-message inconsistency
|
||||
- broader excluded-family coverage at documentation and test level
|
||||
|
||||
---
|
||||
|
||||
## Business Validation Questions
|
||||
|
||||
The following open questions emerged from characterization.
|
||||
|
||||
1. Should the general rule remain: participation is available only while the relevant participation period is open?
|
||||
2. Should Householder participation remain LPA-only?
|
||||
3. If Householder participation is unavailable, should users be shown an explanation?
|
||||
4. Should CPO use a separate participation deadline from most other cases?
|
||||
5. Should all CPO unavailable/ended messages use the same deadline consistently?
|
||||
6. Should ROW hearing remain date-gated?
|
||||
7. Should ROW non-hearing remain generally available?
|
||||
8. What should happen when ROW process information is missing or unclear?
|
||||
9. Should Advert written reps remain LPA-only?
|
||||
10. Should Advert hearing remain available to all participant types?
|
||||
11. Should Advert other process types remain blocked?
|
||||
12. Should consultation participation remain intentionally separate from general representation participation?
|
||||
13. Should missing process information ever default to allowed participation?
|
||||
14. Should portal areas interpret the same process information consistently when different compatibility fields are populated?
|
||||
15. Should string and numeric appeal-type inputs behave the same way?
|
||||
|
||||
---
|
||||
|
||||
## Architectural Conclusions
|
||||
|
||||
The characterization work supports the following conclusions.
|
||||
|
||||
1. The portal is making **one broad participation-availability decision**, not a set of unrelated visibility decisions.
|
||||
2. The current behaviour is best described as a **coherent policy with layered exceptions**.
|
||||
3. The policy has grown **organically over time**, which explains the mix of structured rules and compatibility-sensitive divergence.
|
||||
4. Future work in this area should be driven by **business decision modelling**, not by superficial code cleanup.
|
||||
5. CRM field variants, string-vs-number input behaviour, and consumer divergence are all part of the current live contract and must be preserved unless a deliberate behaviour change is approved.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `docs/representation-participation-business-review.md`
|
||||
- `lib/domain/representation-policy/README.md`
|
||||
- `docs/query-profile-compatibility.md`
|
||||
@@ -0,0 +1,229 @@
|
||||
# Representation Participation Rules – Business Review
|
||||
|
||||
## Purpose
|
||||
|
||||
This document describes the portal’s current observed behaviour when deciding whether someone can take part in a representation or consultation process.
|
||||
|
||||
It is intended for:
|
||||
|
||||
- product owners
|
||||
- business analysts
|
||||
- subject matter experts
|
||||
- service owners
|
||||
|
||||
This is **not** a technical design document.
|
||||
|
||||
It does not describe how the system is implemented.
|
||||
|
||||
Its purpose is to help the business confirm whether the portal currently behaves as intended.
|
||||
|
||||
---
|
||||
|
||||
## Plain English Summary
|
||||
|
||||
The portal appears to be making one broad decision:
|
||||
|
||||
> Can this participant take part in this case at this point in the process?
|
||||
|
||||
Current observed behaviour suggests that the answer depends on:
|
||||
|
||||
- case type
|
||||
- process type
|
||||
- participant type
|
||||
- whether the participation period is open
|
||||
- whether the case is being treated as a consultation
|
||||
|
||||
The portal mostly follows a general pattern, but some case types appear to have special exceptions.
|
||||
|
||||
Some differences in current behaviour may also be historical rather than intentional.
|
||||
|
||||
---
|
||||
|
||||
## General Cases
|
||||
|
||||
Current observed behaviour suggests:
|
||||
|
||||
- participation is generally available for most case types
|
||||
- participation is only available while the relevant participation period is open
|
||||
- once that period ends, participation is no longer available
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. Is this still the correct general rule?
|
||||
2. Should participation normally depend on an open participation period?
|
||||
|
||||
---
|
||||
|
||||
## Householder Cases
|
||||
|
||||
Current observed behaviour suggests:
|
||||
|
||||
- Local Planning Authorities can participate
|
||||
- other participant types cannot participate
|
||||
- where participation is unavailable, users may not always be shown an explanatory message
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. Should Householder participation remain restricted to Local Planning Authorities only?
|
||||
2. If participation is unavailable, should users be shown an explanation?
|
||||
|
||||
---
|
||||
|
||||
## Compulsory Purchase Order Cases
|
||||
|
||||
Current observed behaviour suggests:
|
||||
|
||||
- participation is controlled by a specific participation period
|
||||
- this case type appears to use a different participation deadline from most other cases
|
||||
- participation messages may not always use that deadline consistently
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. Is a separate participation deadline expected for these cases?
|
||||
2. Should all participation messages for these cases use the same deadline consistently?
|
||||
|
||||
---
|
||||
|
||||
## Rights of Way Cases
|
||||
|
||||
Current observed behaviour suggests:
|
||||
|
||||
### Hearing cases
|
||||
|
||||
- participation is only available during a defined participation period
|
||||
|
||||
### Non-hearing cases
|
||||
|
||||
- participation is generally available
|
||||
|
||||
### Where process information is missing or unclear
|
||||
|
||||
- participation may still be treated as available
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. Should hearing cases be restricted to a participation period?
|
||||
2. Should non-hearing cases remain generally available?
|
||||
3. What should happen if process information is missing or unclear?
|
||||
4. Should missing or unclear process information ever prevent participation?
|
||||
|
||||
---
|
||||
|
||||
## Advertisement Cases
|
||||
|
||||
Current observed behaviour suggests:
|
||||
|
||||
### Written representation cases
|
||||
|
||||
- Local Planning Authorities may participate
|
||||
- other participant types may not participate
|
||||
|
||||
### Hearing cases
|
||||
|
||||
- participation is available to all participant types
|
||||
|
||||
### Other process types
|
||||
|
||||
- participation is not available
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. Is this behaviour correct?
|
||||
2. Should written representation cases remain restricted to Local Planning Authorities?
|
||||
3. Should hearing cases remain open to all participant types?
|
||||
4. Should other process types remain blocked?
|
||||
|
||||
---
|
||||
|
||||
## Consultation Cases
|
||||
|
||||
Current observed behaviour suggests:
|
||||
|
||||
- some participation routes are treated as consultations rather than representations
|
||||
- consultation participation is controlled by consultation dates
|
||||
- consultation participation appears to be handled separately from general representation participation
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. Is consultation participation intentionally separate from representation participation?
|
||||
2. Should consultation dates control availability?
|
||||
|
||||
---
|
||||
|
||||
## Missing or Conflicting Information
|
||||
|
||||
Current observed behaviour suggests that participation can depend on how process information is available.
|
||||
|
||||
In some cases:
|
||||
|
||||
- missing information may still allow participation
|
||||
- incomplete information may block participation
|
||||
- different portal areas may interpret the same situation differently
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. If process information is missing, should participation be:
|
||||
- allowed
|
||||
- blocked
|
||||
- decided another way
|
||||
2. If process information is conflicting, how should the portal decide?
|
||||
3. Are there cases where missing information should always prevent participation?
|
||||
|
||||
---
|
||||
|
||||
## Current Known Differences Between Portal Areas
|
||||
|
||||
Current observed behaviour suggests that some portal areas may interpret the same case information differently.
|
||||
|
||||
Examples of this include situations where:
|
||||
|
||||
- one area treats process information as sufficient to allow participation
|
||||
- another area treats the same case as needing further restriction
|
||||
- unavailable messages may not always be shown in the same way
|
||||
|
||||
These differences may be historical rather than intentional.
|
||||
|
||||
### Business validation questions
|
||||
|
||||
1. Should all portal areas interpret the same participation information in the same way?
|
||||
2. Are any current differences intentional?
|
||||
3. If differences are not intentional, which behaviour should be treated as correct?
|
||||
|
||||
---
|
||||
|
||||
## Business Review Checklist
|
||||
|
||||
Use this table to record whether the current observed behaviour matches business expectation.
|
||||
|
||||
| Area | Current Behaviour | Agree? | Notes |
|
||||
| ------------------------------- | ---------------------------------------------------------------------------------------------- | ------ | ----- |
|
||||
| General cases | Participation generally available while the participation period is open | | |
|
||||
| Householder | Only Local Planning Authorities can participate | | |
|
||||
| CPO | Participation controlled by a separate participation deadline | | |
|
||||
| ROW hearing | Participation available only during the relevant participation period | | |
|
||||
| ROW non-hearing | Participation generally available | | |
|
||||
| Advert written reps | Only Local Planning Authorities can participate | | |
|
||||
| Advert hearing | All participant types can participate | | |
|
||||
| Advert other process types | Participation not available | | |
|
||||
| Consultation | Participation controlled separately by consultation dates | | |
|
||||
| Missing process information | Participation may still be allowed in some cases | | |
|
||||
| Conflicting process information | Different portal areas may currently interpret this differently | | |
|
||||
| Ended participation messages | Participation becomes unavailable, but explanation/messages may not always be fully consistent | | |
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
- This document describes **current observed behaviour**.
|
||||
- Some current behaviour may exist for historical reasons.
|
||||
- This document is intended for validation, not implementation.
|
||||
- No changes should be made on the basis of this document alone.
|
||||
- Any future change should be confirmed through business decision-making and protected by characterization before implementation.
|
||||
|
||||
---
|
||||
|
||||
## Related Technical Documentation
|
||||
|
||||
For the technical characterization and compatibility details, see:
|
||||
|
||||
- `docs/representation-participation-availability.md`
|
||||
@@ -18,6 +18,41 @@ Follow-ups:
|
||||
|
||||
---
|
||||
|
||||
### CL-2026-06-18-RPA-DOCS: representation participation availability documentation + context update
|
||||
|
||||
date: 2026-06-18
|
||||
author: Cline
|
||||
scope: `docs/representation-participation-availability.md`, `docs/representation-participation-business-review.md`, `context/current-platform-state.md`, `memory-bank/{techContext,productContext,open-questions,change-log}.md`
|
||||
type: change
|
||||
rationale: Preserve the completed Representation Participation Availability investigation in repository documentation and project context so future contributors do not need to repeat the same discovery work.
|
||||
impact: Documentation/context only; improves architectural clarity and business-validation readiness; no runtime, auth, i18n, or API behaviour change.
|
||||
status: completed
|
||||
|
||||
Summary:
|
||||
|
||||
- Added first-class technical documentation for Representation Participation Availability.
|
||||
- Added a plain-English business review document for product/business/SME validation.
|
||||
- Updated platform and memory-bank context to record:
|
||||
- the stream as complete from a technical discovery/documentation perspective
|
||||
- the architectural conclusion that representation participation is one coherent decision model with layered exceptions
|
||||
- the current state as awaiting business validation before further representation-policy adoption/expansion/change work
|
||||
- the next likely discovery candidate: Case Lifecycle / Status Decision Model Discovery
|
||||
- Added a concise open-questions entry pointing business stakeholders to the new review/technical documentation.
|
||||
|
||||
Validation:
|
||||
|
||||
- Documentation/context update only.
|
||||
- No application code changed.
|
||||
- No tests changed.
|
||||
- Lint/tests skipped because this was documentation-only work.
|
||||
|
||||
Follow-ups:
|
||||
|
||||
- Review `docs/representation-participation-business-review.md` with business stakeholders.
|
||||
- Do not broaden representation-policy boundaries further until validation outcomes are agreed.
|
||||
|
||||
---
|
||||
|
||||
### CL-22541: breadcrumb/back-link route-state helper extraction (`va/adv/ads/key`)
|
||||
|
||||
date: 2026-04-09
|
||||
|
||||
@@ -88,3 +88,37 @@ Technical lead + DevOps owner
|
||||
|
||||
Decision deadline:
|
||||
Before runtime-affecting refactor or next deployment process update
|
||||
|
||||
---
|
||||
|
||||
### Q-004: Representation Participation Availability business validation
|
||||
|
||||
date: 2026-06-18
|
||||
author: Cline
|
||||
scope: representation participation availability across summary/search/domain policy
|
||||
type: question
|
||||
rationale: Technical characterization is complete, but several compatibility-sensitive behaviours may be historical rather than intentional and need business confirmation before any further representation-policy adoption or behaviour change work.
|
||||
impact: User-facing participation availability, blocked messaging, cross-portal consistency, and future domain-boundary decisions.
|
||||
status: open
|
||||
|
||||
Question:
|
||||
Which current representation participation behaviours are intended business rules, and which are historical compatibility behaviours only?
|
||||
|
||||
Needed from:
|
||||
Product owner + business analyst + relevant SME/CRM data owner
|
||||
|
||||
Decision deadline:
|
||||
Before any further representation-policy adoption, expansion, normalization, or behavioural change work
|
||||
|
||||
Current context:
|
||||
|
||||
- Technical characterization and documentation are now recorded in:
|
||||
- `docs/representation-participation-availability.md`
|
||||
- `docs/representation-participation-business-review.md`
|
||||
- Business validation is especially needed for:
|
||||
- Rights of Way behaviour when process information is incomplete or stored differently
|
||||
- Advertisement behaviour when process information is incomplete or conflicting
|
||||
- whether all portal areas should behave consistently
|
||||
- Householder blocked-message suppression
|
||||
- CPO ended-message / deadline consistency
|
||||
- missing or conflicting process information handling
|
||||
|
||||
@@ -27,9 +27,25 @@
|
||||
|
||||
- Case summary UI varies by appeal type and case attributes.
|
||||
- Representation actions are conditionally shown by appeal type, role, and date windows.
|
||||
- Representation participation now appears to form one broader business decision model: whether a participant can engage in representation or consultation activity for a case at that point in the process.
|
||||
- Locale-sensitive behavior affects links, routes, labels, and email template choice.
|
||||
- New-case-reference notifications include preferred-language checks before template selection.
|
||||
|
||||
## Current representation participation state
|
||||
|
||||
- Technical discovery/documentation for Representation Participation Availability is complete.
|
||||
- The current behaviour is best understood as a coherent participation-availability policy with layered appeal-type, process-type, participant-type, consultation, and date-window exceptions.
|
||||
- Business validation is still required before any further representation-policy adoption, expansion, or behavioural change work.
|
||||
- Reference documents:
|
||||
- `docs/representation-participation-availability.md`
|
||||
- `docs/representation-participation-business-review.md`
|
||||
|
||||
## Likely next discovery candidate
|
||||
|
||||
- Case Lifecycle / Status Decision Model Discovery
|
||||
- expected focus: case progress, stages, statuses, closed states, dashboard grouping, and lifecycle messaging
|
||||
- should be treated as discovery-only pending review of the new representation participation documentation
|
||||
|
||||
## Important user-facing behaviors
|
||||
|
||||
- Welsh route aliases are mapped in `next.config.js` and must remain in sync with page behavior.
|
||||
|
||||
@@ -43,6 +43,18 @@
|
||||
- Formatting conventions from `.prettierrc`: 4 spaces, no trailing commas.
|
||||
- Prisma client generation script available: `npm run prisma:generate`.
|
||||
|
||||
## Current domain documentation status
|
||||
|
||||
- Representation Participation Availability has now been documented as a first-class technical domain characterization.
|
||||
- Technical source-of-truth:
|
||||
- `docs/representation-participation-availability.md`
|
||||
- Business validation companion:
|
||||
- `docs/representation-participation-business-review.md`
|
||||
- Current architectural conclusion:
|
||||
- representation participation is best understood as one coherent decision model with layered exceptions
|
||||
- known consumer divergences and CRM compatibility behaviours are part of the current live contract
|
||||
- future technical adoption/expansion work should wait for business validation before changing behaviour or broadening policy boundaries
|
||||
|
||||
## CI/CD and deployment artifacts
|
||||
|
||||
- `azure-pipelines.yml` exists (legacy-looking Node 10 build pipeline).
|
||||
|
||||
Reference in New Issue
Block a user