Category Manager Briefing Automation

Within the Reporting & Compliance Dashboards layer, briefing automation is the stage that turns a night’s worth of raw compliance output into a short, ranked, per-person document that tells one category manager exactly what changed on their shelves and which fixtures to walk first this morning. The overnight scoring pipeline produces thousands of typed records — a compliance_percentage per fixture, out_of_stock_flags, a misplaced_sku_list, drift flags against yesterday — and almost none of that is actionable in raw form. A manager who owns twelve stores cannot read twelve dashboards before the floor opens; they need one page that says these four fixtures moved, here is why they matter in revenue terms, act on the top two before 9am. This page defines the data contract a briefing consumes and emits, the aggregation-and-ranking architecture that builds it, the weights and routing that tune it, the failure modes that quietly erode trust in it, and the batch windows that let it fan out across a whole chain before the morning reset.

Concept & Data Contract Jump to heading#

A briefing is a pure transformation with two hard boundaries. At the inbound boundary it reads the same typed compliance payload that the rest of this section consumes — the output of the Time-Series Compliance Drift Analysis and scoring stages — and at the outbound boundary it emits a typed briefing document, never a free-form string. Keeping the output typed is what lets the render step, the delivery step, and the dedupe step all operate on the same object without re-parsing prose.

The inbound record for a single fixture carries everything the ranker needs to reason about impact: the compliance_percentage and its day-over-day delta, the out_of_stock_flags list, the misplaced_sku_list, a price_tag_mismatch_count, the capture_timestamp the score was computed against, and the registry_revision the fixture was scored under. The briefing groups these by the category manager who owns the store_id and category, ranks the resulting candidate items, and truncates to a readable length. A rendered briefing document looks like this:

{
  "briefing_id": "CMB-2026-07-16-mgr-a41",
  "manager_id": "mgr-a41",
  "generated_for_date": "2026-07-16",
  "source_capture_window": "2026-07-15T22:00:00Z/2026-07-16T05:30:00Z",
  "registry_revision": 184,
  "item_count": 4,
  "items": [
    {
      "rank": 1,
      "store_id": "STORE-1187",
      "fixture_id": "BAY-014-SHELF-03",
      "headline": "Compliance dropped 14 points overnight",
      "compliance_percentage": 71.0,
      "compliance_delta": -14.0,
      "out_of_stock_flags": ["00012345678905", "00098765432107"],
      "misplaced_sku_list": ["00055500011234"],
      "impact_score": 88.4,
      "reason": "2 OOS on eye-level hero SKUs; high revenue leverage",
      "recommended_action": "walk BAY-014 first; restock hero facings"
    }
  ],
  "suppressed_repeat_count": 3
}

Two fields carry more weight than they look. impact_score is the single ranked quantity the whole document is sorted on, and its derivation is the subject of the next two sections. suppressed_repeat_count records how many candidate items were withheld because they were unchanged from yesterday’s briefing — surfacing the count keeps the dedupe honest and gives a manager a way to ask “what’s been sitting open for three days” without those stale items crowding out today’s new movement. Every briefing pins the registry_revision and the source_capture_window so a document can never be misread: if a store’s overnight capture was thin, the window makes that explicit rather than letting a stale score masquerade as fresh. The briefing is idempotent in briefing_id, which is derived from the manager and the target date, so a re-run of the generator overwrites rather than duplicates.

Implementation Architecture Jump to heading#

The generator decomposes into four steps that map one-to-one onto the pipeline diagram: aggregate the overnight records per manager, score and rank each candidate item, suppress day-over-day repeats, then render and hand off to delivery. The ranking step is the heart of it, and it is deliberately a small, testable pure function rather than logic smeared across a template — a category manager will only trust a briefing whose ordering they can predict.

Scoring and ranking candidate items Jump to heading#

The impact score fuses the magnitude of the compliance drop, the count and revenue leverage of out-of-stock and misplaced items, and a recency-of-change signal, each weighted so the ordering matches how a merchandiser would triage by hand. Revenue leverage is what stops a 20-point drop on a slow bottom-shelf SKU from outranking a 6-point drop on an eye-level hero facing:

from dataclasses import dataclass


@dataclass(frozen=True)
class ComplianceItem:
    store_id: str
    fixture_id: str
    compliance_percentage: float
    compliance_delta: float          # negative means it got worse
    out_of_stock_flags: list[str]
    misplaced_sku_list: list[str]
    revenue_weight: float            # 0..1 leverage of this fixture's category


@dataclass(frozen=True)
class RankingWeights:
    drop_weight: float = 3.0
    oos_weight: float = 8.0
    misplaced_weight: float = 4.0
    revenue_gain: float = 1.5        # multiplier on revenue leverage


def impact_score(item: ComplianceItem, w: RankingWeights) -> float:
    """Revenue-weighted urgency for one fixture. Higher means act sooner.

    Only negative deltas contribute; a fixture that improved overnight is
    never surfaced as an action item, though it may appear in a wins digest.
    """
    drop = max(0.0, -item.compliance_delta) * w.drop_weight
    oos = len(item.out_of_stock_flags) * w.oos_weight
    misplaced = len(item.misplaced_sku_list) * w.misplaced_weight
    base = drop + oos + misplaced
    leverage = 1.0 + item.revenue_weight * w.revenue_gain
    return round(base * leverage, 1)


def rank_items(
    items: list[ComplianceItem], w: RankingWeights, max_items: int
) -> list[tuple[ComplianceItem, float]]:
    """Score, drop zero-impact fixtures, sort descending, truncate to max_items."""
    scored = [(it, impact_score(it, w)) for it in items]
    actionable = [(it, s) for it, s in scored if s > 0.0]
    actionable.sort(key=lambda pair: pair[1], reverse=True)
    return actionable[:max_items]

Deduplicating against yesterday and rendering Jump to heading#

Once the top items are chosen, the generator suppresses any that are byte-for-byte the same problem the manager already saw, then renders through a Jinja2 template so the presentation layer is owned by a designer-editable file rather than buried in Python. Jinja2 is the deliberate choice here: the same rendered item dictionary drives a markdown briefing, an HTML email, and a Slack block by swapping only the template, so the ranking logic never forks per channel.

import hashlib
from jinja2 import Environment, select_autoescape


def item_fingerprint(store_id: str, fixture_id: str, flags: list[str]) -> str:
    """Stable identity for a problem so an unchanged item can be suppressed."""
    payload = f"{store_id}|{fixture_id}|{'|'.join(sorted(flags))}"
    return hashlib.sha256(payload.encode()).hexdigest()[:16]


def suppress_repeats(
    ranked: list[tuple[ComplianceItem, float]], seen_yesterday: set[str]
) -> tuple[list[tuple[ComplianceItem, float]], int]:
    kept, suppressed = [], 0
    for item, score in ranked:
        fp = item_fingerprint(
            item.store_id, item.fixture_id,
            item.out_of_stock_flags + item.misplaced_sku_list,
        )
        if fp in seen_yesterday:
            suppressed += 1
            continue
        kept.append((item, score))
    return kept, suppressed


def render_briefing(manager_id: str, kept, suppressed: int, template_src: str) -> str:
    env = Environment(autoescape=select_autoescape(["html", "xml"]))
    template = env.from_string(template_src)
    return template.render(
        manager_id=manager_id,
        items=[{"rank": i + 1, "item": it, "score": s}
               for i, (it, s) in enumerate(kept)],
        suppressed_repeat_count=suppressed,
    )

The signals a briefing ranks on originate upstream: an out-of-stock flag is produced by the facings comparison in Automating Facings vs Actuals Validation, and a misplaced entry comes from the slot-mapped position states one stage before it. The briefing generator never recomputes those; it consumes them, which is why the whole document can be built with a handful of pure functions and a template rather than any vision code.

Production Configuration & Tuning Jump to heading#

Everything that changes the shape of a briefing — the ranking weights, how many items a manager sees, when they may be paged, and who receives what — lives in versioned configuration, never in code, so a merchandising lead can retune the triage without a deploy. A typical config scopes weights and limits by role, because a store-level manager wants a tight action list while a regional lead wants a wider roll-up:

briefing:
  ranking_weights:
    drop_weight: 3.0
    oos_weight: 8.0          # out-of-stock dominates; it is lost sales now
    misplaced_weight: 4.0
    revenue_gain: 1.5        # multiplier applied to per-fixture revenue leverage
  max_items_per_briefing: 7  # hard ceiling; above this managers stop reading
  min_impact_score: 12.0     # below this, an item is not worth a line
  dedupe:
    lookback_days: 1
    escalate_after_days: 3   # an item open this long is re-surfaced, flagged
  quiet_hours:
    send_after_local: "06:30"
    send_before_local: "20:00"
  routing:
    store_manager:  { max_items_per_briefing: 5, channels: ["slack", "email"] }
    regional_lead:  { max_items_per_briefing: 15, channels: ["email"] }
    category_head:  { channels: ["email", "dashboard"] }

The two settings that most shape trust are max_items_per_briefing and min_impact_score. Set max_items too high and the briefing becomes a wall of text a manager stops opening; the ceiling of 7 reflects a real limit on what someone will action before the floor gets busy. The min_impact_score floor of 12.0 is what keeps a cosmetically-shifted single facing off a document reserved for genuine revenue movement — it is the throttle against alert fatigue, and it should be tuned against how many items managers actually close per day, not guessed. oos_weight sits highest at 8.0 because an out-of-stock is lost sales in the present tense, whereas a compliance-percentage drift is a leading indicator. The escalate_after_days rule at 3 is the deliberate counterweight to dedupe: a problem that keeps getting suppressed for being unchanged is re-surfaced with an escalation flag so silent suppression never becomes silent neglect. Quiet hours and per-role routing keep the generator from paging a store manager at 4am with a digest meant for 7am; anything genuinely time-critical does not belong in a briefing at all and should route through Real-Time Compliance Alerting & Webhooks instead, which is the digest-versus-alert boundary this section draws deliberately.

Failure Modes & Debugging Workflow Jump to heading#

When a briefing is wrong, distrusted, or ignored, the cause is almost always one of five recurring problems. Work them in this order:

1. Alert fatigue from too many items. Symptom: managers report they have stopped opening the briefing, or open rates decay over weeks. Root cause is almost always a max_items_per_briefing or min_impact_score set too loose, so the document reads as noise. Reproduce by counting median items per briefing over the last two weeks against how many managers actually close per day. Fix by tightening min_impact_score first and only then lowering max_items — the goal is that every line on the page is worth walking to, not that the page is full.
2. Briefing sent before overnight scoring finished. Symptom: item counts are implausibly low or a manager’s busiest stores are missing entirely. Root cause is the generator firing on a fixed clock rather than a completion signal, so it reads a half-written compliance store. Reproduce by comparing the briefing’s source_capture_window against the scoring job’s actual finish time. Fix by gating generation on an explicit “scoring complete for this window” watermark — a batch that has not signaled completion must block the briefing, never race it.
3. Stale data on capture gaps. Symptom: a store shows suspiciously unchanged, healthy numbers day after day while its neighbors move. Root cause is that the store’s overnight captures failed and the briefing is silently reusing an old capture_timestamp. Reproduce by checking capture recency per store_id against the window. Fix by treating a fixture with no fresh capture in the window as unknown, not compliant — surface a “no data” note rather than a stale-but-green line, and coordinate with the offline-resilience handling in Fallback Routing for Offline Store Scenarios so a connectivity gap is visibly a gap.
4. Duplicate items day over day. Symptom: the same fixture appears at rank one every morning and managers complain the briefing never changes. Root cause is a fingerprint that is too coarse or a dedupe lookback that is not being persisted between runs. Reproduce by hashing today’s items against yesterday’s stored fingerprints and confirming the set actually loaded. Fix by verifying item_fingerprint includes the specific flag list, confirm the previous day’s fingerprints are being read from durable storage, and lean on escalate_after_days to convert a genuine long-open problem into an escalation rather than a silent repeat.
5. Wrong recipient mapping. Symptom: a manager receives fixtures from stores they do not own, or a store’s problems reach no one. Root cause is a stale store_id-to-manager ownership table, usually after a territory reorganization. Reproduce by auditing a sample of briefings against the current org chart. Fix by sourcing the ownership map from the system of record on every run rather than a cached copy, and fail a briefing loudly when a store_id resolves to no owner instead of dropping it silently — an unowned store is a routing bug, not an empty briefing.

Keep a labeled log bucketed by these five causes and review which dominates each month; a rising alert-fatigue bucket means retune weights, a rising timing bucket means fix the completion watermark, and a rising routing bucket means the ownership sync is the real project. The child walkthrough Generating Morning Reset Briefings from Compliance Data works a concrete end-to-end example against these same failure modes.

Scaling & Performance Benchmarks Jump to heading#

A briefing is cheap to build and expensive only in fan-out. Generating one manager’s document — aggregate, score, dedupe, render — is a handful of pure functions over a few hundred records and completes in single-digit milliseconds; a full chain of 2,000 stores across a few hundred managers generates in well under a minute of wall-clock time on a single worker. The real constraint is the window, not the throughput: every briefing must be built after overnight scoring completes and delivered before the morning reset, so the generator runs in a fixed batch window rather than continuously, and it is the completion watermark from the scoring stage — not a wall-clock cron — that opens that window.

Fan out the generation by category and banner so each manager’s briefing is an independent unit of work; there is no cross-manager state once aggregation has grouped the records, which makes the batch embarrassingly parallel and lets a burst — a chain-wide reset that scored late — clear by adding workers linearly. Partition the work queue by manager_id to preserve per-manager ordering and to make the dedupe read of yesterday’s fingerprints a clean per-partition lookup. Delivery must be idempotent: key each send on the briefing_id, which is derived from manager and date, so a retried or re-run batch overwrites the same document and re-sends at most once rather than double-paging a manager. Design against a soft SLA of the full chain delivered within 15 minutes of the scoring watermark, and monitor the gap between watermark and last-delivery rather than CPU — a widening gap almost always means the scoring stage finished late, not that generation is slow. Cost discipline mirrors the rest of the platform: the generator reads the already-summarized compliance records this section’s Compliance Score APIs & Payload Contracts expose, never raw frames or detections, so it stays a rounding error on the analytics bill even while producing a per-manager, per-day audit trail across the whole estate.

Frequently Asked Questions Jump to heading#

Related Jump to heading#

• Generating Morning Reset Briefings from Compliance Data — the end-to-end walkthrough that builds one briefing against a real overnight window
• Real-Time Compliance Alerting & Webhooks — the interrupt-driven sibling for time-critical events, the other side of the digest-versus-alert boundary
• Automating Facings vs Actuals Validation — the upstream stage that produces the out-of-stock and facing signals a briefing ranks on
• Reporting & Compliance Dashboards — the parent layer that turns the typed compliance payload into APIs, drift analytics, alerts, and briefings