Context Buckets & Lessons Learned

Context Buckets are light-weight database tables, one per core module, that store patterns we never want to forget.
They turn hard-won experience (human or AI) into machine-readable guard-rails that prevent repeat mistakes and bias future reasoning.

The schema and examples below are aligned with the original design notes in docs_archive/context-buckets.md.

1. Why Do We Need Them?

Pain-point	Context-Bucket Solution
A participant repeatedly “fake-cancels” appointments via text.	Store a behaviour pattern so the cancellation handler requires human confirmation before actioning.
A specific vehicle frequently has issues with a particular seat.	Lower the auto-allocation confidence for that seat when the vehicle appears in suggestions.
A staff member consistently declines last-minute overtime shifts.	Reduce their ranking in automated shift-swap suggestions.
An external API endpoint is flaky during nightly maintenance.	Flag a retry-with-backoff strategy instead of letting the service fail immediately.

Context Buckets inform decisions before they happen, unlike post-hoc analytics which only explain past failures.

2. Current bucket taxonomy

Buckets should stay broad and instinctive. They are not severity categories; they are the operational "desk" where a memory naturally belongs. Severity, safety risk, urgency, financial impact, exposure, confidence, repeatability, and decay are scoring dimensions handled by Chapter 07.

Use the smallest stable set that maps to how the team already thinks about work:

ID	Bucket	Includes
1	System / Agents / AI / SPA / SAEDI	Reggie, Henry, agent/runtime behaviour, SPA/SAEDI droids, system automation.
2	Comms & I/O	SMS, email, Discord, inbound/outbound messages, notification flows, external I/O.
3	Finance / Billing / Plan Management	Billables, invoices, NDIS/PM effects, payment/billing anomalies.
4	Admin / Accounts / Legal / Consent / Authority / Compliance / Quality	Office/admin work, accounts admin, authority, approvals, compliance and quality artifacts.
5	Participants / Customer Service / Health / Medications / Clinical / Individual Planning	Participant support, ROC/BSP/MM-style planning, health, meds, clinical alerts, customer-service context.
6	Staff / HR	Staff records, employment, HR, training, performance, availability patterns.
7	Roster / Schedule / Intents	Rosters, schedule projection, future changes, engine intents.
8	Programs / Activities / Service Delivery	Program blueprints, activities, service delivery content and outcomes.
9	Assets / Facilities / Venues	Buildings, rooms, equipment, venue issues, asset condition.
10	Transport	Vehicles, routes, drivers, pickup/dropoff, transport operations.
11	Data / Reports / Analytics / Incidents	Reports, dashboards, analysis outputs, incident report artifacts.
12	SIL / STR	SIL and STR-specific operations and service context.
13	Support Coordination	Support coordination actions, provider coordination, external support links.
14	Media / Publications	Gallery/media, publications, newsletters, social/content outputs.
99	Unclassified / Misc	Temporary holding bucket; treat as a trace/classification gap to clean up.

Classification rule

Pick the bucket by domain, not by alarm level. A participant emergency remains a Participants/Health event; a vehicle emergency remains a Transport event; a venue hazard remains an Assets/Facilities/Venues event. The urgency is expressed through scoring, not by moving the event to a separate emergency bucket.

Incident report rule

An incident report itself belongs in 11 Data / Reports / Analytics / Incidents and can become the O-Tag catalyst for the chain. When the report is analysed, it may spawn linked follow-up entries into relevant buckets:

medication or care-plan follow-up -> bucket 5;
staff supervision/training follow-up -> bucket 6;
roster/intents correction -> bucket 7;
activity/service change -> bucket 8;
venue hazard/repair -> bucket 9;
vehicle/route review -> bucket 10;
compliance/authority review -> bucket 4.

Those spawned items retain the incident report O-Tag. New R-Tags are created only where a meaningful decision or action branch occurs.

3. Standard Schema (PostgreSQL)

Every module creates its own table named <module>_context_bucket.

CREATE TABLE transport_context_bucket (
  id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  pattern_type       TEXT    NOT NULL,  -- e.g. 'CANCELLATION_BEHAVIOUR'
  entity_id          TEXT    NOT NULL,  -- e.g. 'participant_id:123', 'vehicle_id:V4'
  observation        TEXT    NOT NULL,
  recommended_action TEXT    NOT NULL,  -- 'ESCALATE', 'IGNORE', 'REQUIRE_REVIEW'
  confidence         NUMERIC(3,2) NOT NULL, -- 0.00–1.00
  source             TEXT    NOT NULL,  -- 'manual', 'llm', 'import'
  vector             VECTOR(768),       -- embedding of observation
  created_at         TIMESTAMPTZ DEFAULT NOW(),
  updated_at         TIMESTAMPTZ DEFAULT NOW()
);

4. Integration Pattern

Pre-check – Before executing critical logic, a module queries its own context bucket for patterns that match the entities involved.
Decision tweak – A high-confidence match can either
- automatically adjust the logic (e.g., skip a cancellation, choose a different vehicle), or
- require human approval by creating a Cognitive-Alignment review task.
Post-write – After an action completes, if it reveals a new lesson (e.g., a rejected claim), the module writes or updates an entry.
Decay – A nightly job gradually reduces confidence for patterns that haven’t been re-affirmed, allowing stale lessons to fade.

5. Maintenance & Best Practices

Controlled vocabulary – Keep pattern_type values in a shared enum to avoid lookup errors.
Confidence decay – Nightly cron lowers confidence for untouched patterns (e.g., confidence -= 0.02).
Source tracking – Distinguish manual vs llm to apply different review thresholds.
Pruning – Periodically purge low-confidence (< 0.1) entries to keep buckets efficient.

6. Recurrence, decay, and concept-level reinforcement

Decay is not just a tidiness mechanism. The shape of decay determines whether the buckets feel humanly correct to the people relying on them. Two failure modes have to be avoided at once:

Amnesia -- a genuine ongoing problem is erased because individual instances are spread out over time and each one decays independently.
Permanence -- a repeated problem keeps accumulating weight forever, so it ends up feeling unsolvable even after it has actually been addressed.

The bucket model handles this through three coordinated behaviours rather than one global decay knob.

6.1 Per-instance decay

Each entry in a context bucket decays on its own clock. An old, unrepeated cancellation by Bob should fade out of the active set whether or not other unrelated cancellations are happening elsewhere. This is the cron mentioned in Section 4 above (confidence -= 0.02 nightly, or whatever the tuned rate ends up being).

Per-instance decay alone is too forgetful: a parent who cancels every fortnight would never accumulate a visible pattern, because each individual instance fades faster than the next one arrives.

6.2 Concept-level reinforcement

Repeated instances of the same concept -- same entity, same pattern_type, or sharing an O-Tag family or V-Pol category from the Tag Trinity -- lift each other's weight rather than each living and dying alone.

In practice this is implemented as a family boost that the relevance scorer in Chapter 07 reads off the bucket. Frequency increments when a new instance is observed, and the family boost is computed from the cluster of related entries rather than from the single row.

This is what stops amnesia. A pattern that recurs every two weeks stays visible because the cluster's combined weight outpaces any individual entry's decay.

6.3 Ceiling on accumulation

Concept-level reinforcement without a ceiling produces the opposite failure: a long-running but actively-managed pattern drifts up the dashboard and stays there forever, even when the staff watching it know it is being handled.

The buckets impose a soft ceiling on accumulated weight per concept cluster. Above the ceiling, additional repetitions register (frequency keeps climbing, the audit trail keeps growing) but the score does not run away. The ceiling makes "this is a known recurring thing we are managing" a stable state instead of an ever-rising alarm.

The ceiling is tunable per bucket type because the right value differs by domain -- a transport safety incident should ceiling lower (we want every recurrence to keep prompting attention) than a low-stakes "participant prefers afternoon programs" preference pattern.

6.4 Why these three together

Per-instance decay alone gives amnesia. Concept-level reinforcement alone gives permanence. The ceiling alone is meaningless without a reinforcement mechanism for it to constrain.

Run as a system, the three produce buckets that:

preserve real patterns,
avoid obsession,
avoid amnesia,
and keep relevance feeling humanly correct as the dataset ages.

The relevance scorer in Chapter 07 reads these signals (frequency, family boost, decay, ceiling) and produces the dashboard score. The bucket is the substrate; the scorer is the lens.

02_Cognitive_Alignment_&_Review.md
05_Mind_Map_Data_Relationship_Index.md
07_Relevance_Scoring.md
10_Tag_Trinity.md

1. Why Do We Need Them?​

2. Current bucket taxonomy​

Classification rule​

Incident report rule​

3. Standard Schema (PostgreSQL)​

4. Integration Pattern​

5. Maintenance & Best Practices​

6. Recurrence, decay, and concept-level reinforcement​

6.1 Per-instance decay​

6.2 Concept-level reinforcement​

6.3 Ceiling on accumulation​

6.4 Why these three together​

🔗 Related Docs​