Specification Review: Enable Scheduled Managed Charger Access¶
Verdict¶
- Status: Needs more exploration
- Reason: The draft has a useful concept model, but it was written before an exploration dossier and carries several unresolved decisions that would force story shaping or delivery teams to rediscover scope.
- Minimum next step: Run
specification-explorerand create an exploration dossier focused on charger capability, identifier ownership, scheduling semantics, denial UX, operations visibility, rollout, and delivery slicing.
Panel¶
| Perspective | Review focus | Result |
|---|---|---|
| Challenge fit | Does the spec preserve the challenge outcome and constraints? | concerns |
| Underlying model clarity | Are the core concepts stable enough for stories? | concerns |
| User and UX | Are changed surfaces, user flows, states, and support expectations clear? | concerns |
| Business logic and domain | Are rules, edge cases, and policy decisions explicit? | concerns |
| Technical feasibility | Are integration, data, API, and operational implications plausible at the right level? | concerns |
| Delivery readiness | Can story shaping proceed without rediscovering intent? | fail |
| Architecture / ADR | Does the direction account for relevant cross-product decisions? | concerns |
| Release / help / support | Are rollout, docs, and support impacts clear? | concerns |
Findings¶
P1: Missing exploration dossier blocks the new flow¶
- Location: frontmatter and appendices in
spec.md; work index - Issue: The artifact chain has
challenge.mdandspec.md, but no exploration dossier. The Linear initiative currently contains the challenge text, has no projects, and does not appear to hold the specification as the canonical Linear Project artifact. - Why it matters: The current workflow expects
Discovery -> Definition -> Delivery, where exploration informs the concise specification and Linear owns the specification. Without exploration, the draft mixes assumptions, decisions, implementation sequencing, and open questions without the evidence ledger needed for review. - Required change: Create an exploration dossier before revising the spec. Decide whether this repo draft is a temporary working artifact or whether the canonical spec needs to move into a Linear Project.
- Evidence:
spec.mdhas noexploration_ref;index.mdlists only Challenge and Specification; the Linear initiative has no projects and its description mirrors the challenge, not the draft spec.
P1: Charger and protocol capability is a prerequisite, but the spec treats it as a later phase¶
- Location:
spec.mdlines 40-45, 87-89, 231-233, 324-326, 353-354 - Issue: The spec depends on chargers supporting remote freevend switching and pre-start authorisation, but the supported charger/protocol set is still an open question and appears in Phase 1 of the implementation approach.
- Why it matters: If the first supported charger path cannot switch freevend reliably or cannot request authorisation before start, the core product promise and delivery slices change.
- Required change: Explore and document the first supported charger/protocol paths before final spec writing. The spec should separate
unsupported,partially supported, andfully supportedstates with the product behaviour for each. - Evidence:
FR-005andFR-006require mode-change and capability status, while open questions still ask which charger models and protocols support the needed behaviours.
P1: Identifier ownership and lifecycle are unresolved¶
- Location:
spec.mdlines 43, 59, 108-110, 123, 173-175, 233-240, 344-347, 355-357 - Issue: The spec says own-fleet and agreement identifiers will drive access decisions, but it does not identify the authoritative systems, sync timing, active/inactive lifecycle, conflict handling, or what happens when an identifier maps to more than one vehicle or agreement.
- Why it matters: Managed access cannot be sliced safely until the team knows which service owns identity data, how stale data is handled, and what decision reason is shown when classification is uncertain.
- Required change: Explore
Vehicle Access Identityas a primary lane. Capture source systems, update cadence, identifier types, masking or hashing rules, duplicate/conflict rules, and support-facing explanation rules. - Evidence: Agreement management is out of scope, but agreement identifiers are a direct dependency for
FR-009,FR-014, andNFR-006.
P1: Schedule boundary semantics are under-specified for delivery¶
- Location:
spec.mdlines 106-107, 122, 170-171, 228-230, 242, 245, 360-361 - Issue: The spec names timezone-aware recurring schedules, overlaps, daylight-saving transitions, boundary attempts, and possible overrides, but leaves the actual policy unresolved.
- Why it matters: Different choices alter UI validation, persistence, evaluation, tests, and what a charger should do when a session starts near a boundary.
- Required change: Use exploration to settle or explicitly defer schedule policy: recurrence shape, overlap rule, precedence, boundary inclusivity, DST skipped/repeated local times, offline mode-change catch-up, and whether manual overrides exist in phase one.
- Evidence: ADR 0009 supports timezone-aware UTC handling, but it does not define recurrence policy, local-time edge cases, or access-mode boundary behaviour.
P1: Operations visibility and denial UX are too thin for story shaping¶
- Location:
spec.mdlines 44-45, 83-85, 112-114, 193-194, 237-241, 337-338, 358-359 - Issue: The spec requires access-denied events and denial signals, but does not define where users see denials, what they can filter or inspect, how denial differs from faults in existing views, or what driver-facing signals are possible per protocol.
- Why it matters: This hides most of the user-facing product work. Story shaping would have to infer screens, states, language, permissions, and support workflows.
- Required change: Explore the current Manage and operations surfaces before rewriting the spec. Capture the target views, states, permissions, copy, report impact, and protocol-specific denial responses.
- Evidence: The challenge asks for clear separation from charger failure, but the spec still carries the visibility decision as an open question.
P2: The domain model may overcommit to events before architecture and delivery evidence exists¶
- Location:
spec.mdlines 129-176, 212-222, 256-259, 368-372 - Issue: The draft uses a rich eventstorming model and references ADR 0023, but ADR 0023 is proposed, not accepted, and the spec does not distinguish conceptual domain events from implementation events or integration messages.
- Why it matters: Delivery could overbuild an event architecture before the required downstream consumers, idempotency, and delivery guarantees are clear.
- Required change: In exploration, separate conceptual event language from implementation commitments. The revised spec should say which events are product facts, which are audit records, and which require a real event bus or async delivery.
- Evidence: ADR 0023 recommends domain-event modelling but is still proposed;
NFR-003mentions retries and resilience without defining idempotency or delivery rules.
P2: Release, feature-flag, help-doc, and support follow-through needs sharper ownership¶
- Location:
spec.mdlines 249, 322-349, 362 - Issue: The spec notes feature flags, rollout, operations visibility, and support needs, but leaves rollout stage, help docs, support guidance, and release-note impact open.
- Why it matters: This work changes user-visible behaviour and likely needs help docs, release notes, support language, and flag lifecycle planning before delivery starts.
- Required change: Add release/help/support to exploration. The revised spec should identify the intended flag stage, rollout path, documentation impact, and support handoff.
- Evidence: The BFDev feature-flag guidance and release-note/help-doc workflow apply when Manage behaviour changes.
Traceability Check¶
| Source | Target | Status | Notes |
|---|---|---|---|
| Challenge outcome | Intent / scope | concerns | The spec covers the main outcome, but capability and identifier assumptions remain unproven. |
| Underlying model | Selected spec views | concerns | Terms are useful, but Vehicle Access Identity, scheduling policy, denial visibility, and capability states need exploration. |
| Solution contract | User / UX / technical concerns | concerns | The contract depends on open protocol, UX, and data ownership questions. |
| Spec | Story shaping readiness | fail | Story shaping would need to rediscover key product and technical decisions. |
Open Questions¶
- Blocking:
- Which charger/protocol paths are in the first supported set, and what exact freevend and authorisation controls do they expose?
- What system owns own-fleet identifiers, agreement identifiers, lifecycle state, and conflict resolution?
- What is the exact recurrence, overlap, boundary, DST, and offline catch-up policy for schedules?
- Where do access-denied events appear, who can see them, and what support details are exposed?
- What denial signal can be sent for each supported charger/protocol path?
- Is the canonical specification meant to live in Linear Project form, or is this repo draft an agreed exception?
- Non-blocking:
- Should manual overrides be included in phase one or left as a named later capability?
- Should access-denied events appear in customer-facing reports in the first release?
- Which feature-flag stage should be used for the first exposure?
ADR Check¶
- Relevant ADRs found:
- ADR 0009 requires timezone-aware datetime handling and UTC internal storage. The spec aligns with this, but recurrence and DST policy still need product decisions.
- ADR 0011 names centralized feature flags through LaunchDarkly, while local process docs now describe GitLab Feature Flags and Unleash for BetterFleet Manage. The revised spec should use current Manage rollout language and avoid raw flag names in release notes.
- ADR 0020 favours additive API evolution where possible. The spec aligns with this at a high level.
- ADR 0023 supports domain-event modelling but is proposed. Treat event names as conceptual unless a later technical design commits to event infrastructure.
Suggested Next Step¶
- Next skill/artifact:
specification-explorerexploration dossier. - Required owner input:
- Confirm whether to create the exploration dossier in this repo alongside the draft, then migrate the final concise specification into Linear Project form.
- Confirm the first charger/protocol candidate, or name the technical owner who can provide it.
- Confirm the likely source systems for own-fleet and agreement vehicle identifiers.