Skip to main content

06_Context_Buckets_and_Reason_Tags.md

Manual – Context Buckets, Reason Log, and Reason‑Tag Propagation

This chapter explains how RABS answers why something happened, not just what happened.

1) The idea​

  • Reason Log: the place where decisions are recorded (LLM, human, or system).
  • Context Buckets: narrated streams of system actions across domains (comms, transport, finance, scheduling, compliance).
  • Reason‑Tag (RTag): the UUID that links them. Once issued, it travels through the system until the chain of consequences ends.

Think of buckets as “Reggie’s memories of what happened,” and the Reason Log as “why Reggie (or a person) chose this path.”

2) Current context bucket set​

Buckets should be few, broad, and natural to the team. They identify the operational desk for the event; they do not identify severity. Severity, urgency, risk, financial exposure, confidence, repeatability, and decay are scoring inputs handled by Chapter 07.

IDBucket
1System / Agents / AI / SPA / SAEDI
2Comms & I/O
3Finance / Billing / Plan Management
4Admin / Accounts / Legal / Consent / Authority / Compliance / Quality
5Participants / Customer Service / Health / Medications / Clinical / Individual Planning
6Staff / HR
7Roster / Schedule / Intents
8Programs / Activities / Service Delivery
9Assets / Facilities / Venues
10Transport
11Data / Reports / Analytics / Incidents
12SIL / STR
13Support Coordination
14Media / Publications
99Unclassified / Misc

Bucket 99 is a temporary classification fallback. Repeated use of 99 should be treated as a trace-quality problem, not as a normal destination.

Incident reports as origins​

An incident report artifact belongs in bucket 11. It can become the O-Tag for every programmatic or decision-based action that follows.

After triage, the incident report may spawn linked events into other buckets:

  • participant health/care actions -> bucket 5;
  • staff follow-up -> bucket 6;
  • roster or intent correction -> bucket 7;
  • activity/service redesign -> bucket 8;
  • venue or asset action -> bucket 9;
  • transport action -> bucket 10;
  • compliance/authority review -> bucket 4.

All spawned actions preserve the incident-report O-Tag. They receive new R-Tags only when a meaningful decision branch is made.

3) Everyday examples​

  • “Why isn’t Bob on Saturday’s bus?” → Transport bucket says “I removed Bob…” with a link to the Reason Log: “Because Bob cancelled by SMS on Tuesday.”
  • “Why is Bob’s billing lower?” → Finance bucket points to the same Reason Log. One decision, many consequences, all linked.
  • “Why did this medication review appear?” → Participant/Health bucket links back to an incident report O-Tag and the triage R-Tag that decided follow-up was required.

4) How the Reason‑Tag flows​

  • When a decision is made (LLM or human modal), we create a Reason Log and get its Reason‑Tag.
  • Every service call, queue message, and DB write carries this tag (HTTP header X-Reason-Tag, or a reason_tag column).
  • Days later, when a downstream event occurs (e.g., a shift is picked up), that row still carries the original Reason‑Tag.

If a table can’t take a reason_tag yet: we write to agent_reason_edges (a generic link table) so the chain still exists.

5) Human workflow (mandatory context)​

When a user performs a change that affects customers/staff, show a modal:

  • Reason/Context (free text), Origin (verbal/phone/email/in‑person), optional reference (file, message ID).
  • Backend creates a Reason Log with actor='human'; UI continues with the returned Reason‑Tag attached.

This ensures Reggie can later narrate why even when a human did it offline (“verbal cancellation at the shops”).

6) Admin UI patterns​

  • Reason badge with deep link on every detail page.
  • Open chain → shows all entities linked by the RTag across systems.
  • Top Issues → sorted by the scoring model (severity × frequency × repeatability × decay).
  • Ask Reggie why… → runs a narrated query: pulls bucket events + Reason Log, formats a human answer.

7) Developer contracts​

  • Accept X-Reason-Tag on every write endpoint; re‑emit it downstream.
  • Include it in queue envelopes (meta.reasonTag).
  • DB writes: set reason_tag where the column exists, otherwise add an agent_reason_edges entry.
  • Store or derive the context bucket ID for material events so "why" views and ChainCode exports can group by operational desk.

Lint rule: new write paths must include the RTag; otherwise CI fails.

8) Privacy & safety​

  • Narrate in first person for readability, but keep actor truthful (system|reggie|human|buddy).
  • Do not store raw PII in buckets; store references.
  • Redaction by role in UI and Reggie’s answers.

9) FAQ​

Q: What if multiple reasons converge?
A: Buckets can link to multiple Reason Logs; the UI will say “Driven by: A, later amended by: B”.

Q: What if something happens with no decision?
A: Use actor='system' and a templated Reason Log (“Daily roll‑over”) for the paper trail.

Q: Does this replace RAG?
A: No. RAG is for free‑text search. Reason‑Tags are explicit causal links for precise “why” answers.

  • 01_Prime_Directives.md – how Reggie stays aligned.
  • 03_Grounding_&_Reassurance_Buffer_ItsOk.md – how Reggie speaks under stress.
  • 04_Context_Buckets_and_Lessons_Learned.md – bucket taxonomy and recurrence/decay mechanics.
  • 07_Relevance_Scoring.md – how severity, frequency, decay, and boosts determine active attention.
  • 11_Tag_Matrix.md – matrix and ChainCode export model.

End of chapter