Imported from qntweb/simplebooking-claude-plugin (simplebooking/skills/sb-demand-capture/SKILL.md). Install upstream with npx skills add qntweb/simplebooking-claude-plugin --skill sb-demand-capture. Copyright stays with the author.

🎯 sb-demand-capture — Cross-check of demand × actual sales

Overview

sb-revenue-lens knows how to read area demand (searches across the destination, availability, restrictions, price). sb-reservation-insights knows how to read actual sales (pickup, channel mix, markets, cancellations) from the Back Office. Neither one, alone, can answer "the demand for my dates is there, but am I actually selling it?" — the first sees no single reservation, the second sees no market.

sb-demand-capture exists only to answer this class of question: it takes the hotelier's question, routes it to the two skills over the same period, and owns the comparison logic between their answers.

The triangle, and the term that used to be missing

area demand  →  my shop window  →  sales
      leg 1: visibility     leg 2: conversion

Until recently this skill jumped straight from the first term to the third, and every gap it found had two incompatible readings — they never reach me and they reach me and don't buy — with nothing in the data able to separate them. Every answer could state a size and never a mechanism.

The middle term is now readable: the searches performed on this property's own booking engine, via run_property_demand_aggregation. X1 decomposes into its two legs, X5 and X6 gain a middle term that makes their comparison honest, and two lenses exist that could not before — X8 (visibility) and X9 (denied demand: what a guest asked for and could not be served).

The two legs route to different owners, which is the practical payoff: a visibility leg is sb-direct-attribution's or the marketing side's question, a conversion leg is this skill's and sb-revenue-lens's. Naming the leg is worth more than sizing the total.

Architectural constraint, and its one deliberate exception

This skill orchestrates, it does not recompute. Every number that belongs to another skill comes from an agentic invocation of sb-revenue-lens or sb-reservation-insights, quoted verbatim. If one of the two changes a formula or a threshold tomorrow, this skill doesn't need to be touched — it inherits the change automatically, because it doesn't hold its own copy.

The exception: first-party demand, which this skill reads directly. The constraint above exists to prevent holding a second copy of somebody else's logic. run_property_demand_aggregation has no other owner — no skill reads the searches on the property's own booking engine — so there is no formula to inherit and nothing to drift out of sync. It also adds no new dependency: it sits on the same Back Office MCP that sb-reservation-insights already requires. Reading it here is not a violation of the rule, it is the rule applied to a source that has no home elsewhere.

That exception is narrow and stays narrow. If a future skill takes ownership of first-party demand, this skill goes back to invoking it. Do not extend the exception to anything else: the moment a number exists in another skill, it is fetched from there.

This skill owns: the router for the 9 cross-lenses, first-party demand, the alignment of the time windows, the comparison arithmetic (delta / share / decomposition), the classification thresholds, and the caveat that area demand is about the destination, not the property.

Relationship with sb-monday-brief — declared overlap

sb-monday-brief's Detector 1 ("missed opportunities") already cross-checks OTB/STLY against IBE destination demand — it is, in effect, a reduced version of lens X1 below, computed every Monday with fixed thresholds and a single yes/no outcome. This skill is the on-demand version, driven by the user's question, across 9 lenses and any period. The overlap is intentional, not a defect to fix right away: don't move Detector 1's logic here as long as that detector remains the only one validated on real data for the weekly alert. If they consolidate in the future, Detector 1 should call this skill's X1 instead of recomputing its own version — flag it as technical debt, don't do it silently.

The three sources

Don't resolve the Property ID yourself for the two agentic sources: pass the same name/ID to both invocations and let each do its own resolution (they already do it reliably, and the IDs are shared between the two MCPs). The first-party call takes that same Property ID.

First-party demand is optional. Probe it once; if the tool is unavailable or the call fails on authorization, every lens falls back to its two-point form and the answer states that the decomposition wasn't available. X8 and X9 simply don't run. No lens ever depends on it, and a missing third source is never estimated.

Before starting

You need hotel and period, exactly as for sb-revenue-lens. If the period isn't clear or inferable from context, ask — don't guess it. If a reasonable default exists (see config/defaults.yaml:default_window), use it and always state which period you used.

Router for the 9 cross-lenses

Map the user's question to one or more lenses. If ambiguous, ask with a multiple choice. If the user doesn't ask a specific question ("look at June"), run X1 (the most universal) and offer the others.

Detail of each lens (input, comparison, classification): references/cross-lenses.md. Exactly which call to make to each source, for each lens: references/orchestration.md.

Workflow

1. Identify hotel, period and lens (router above).

2. Invoke sb-revenue-lens with the relevant question/lens over the period. Save the answer (including the evidence-table numbers) verbatim.

3. Invoke sb-reservation-insights with the equivalent question over the same period and, where possible, at the same granularity (weekly — see "Window alignment" in references/orchestration.md). Save the answer verbatim.

4. Read first-party demand for the lenses that use it (X1b, X5, X6, X8, X9 — see the table in references/orchestration.md). Read references/property-demand.md before writing the call: its four mechanical guardrails are not intuitive and produce plausible-looking wrong numbers when ignored. If the tool isn't available, skip this step, drop to the two-point form and say so in the answer.

5. Compute the comparison per the triggered lens. Write the numbers to a JSON and run:

   python3 <skill-dir>/scripts/verify.py claims.json

   If it exits non-zero, the comparison doesn't go into the answer: fix it or state what doesn't add up.

6. Answer: the fact (the numbers, each one's source) and the classification (in line / to verify / marked deviation) — never the cause as a certainty, only as a hypothesis to verify with the hotelier. When the decomposition ran, name the leg that carries the gap rather than reporting the total alone, and hand a visibility leg to the skill that owns it. Always state the destination-vs-property caveat when relevant (almost always, except X2 which is purely mechanical).

7. Offer the branded report, if requested, reusing sb-revenue-lens's script as the layout base (don't write a new one from scratch) — a future extension, see below.

Guardrails

• Not prescriptive advice. Like sb-revenue-lens: show the comparison and 1-3 verification questions, not a "do X".
• Cannibalization — same rule as sb-monday-brief. "Would this guest have booked direct anyway?" isn't measurable here: never assert it.
• The report goes to a customer. In the multi-property comparison (X7), no data from other properties if the output is for a single hotel; the ranking is only for whoever manages the whole portfolio (same rule as sb-monday-brief).
• Fact vs inference always kept distinct, as in sb-revenue-lens.
• If one of the two agentic sources isn't available in the session, stop and state it — don't estimate the missing side with a guessed number. A missing first-party source is different: it degrades, it doesn't stop. Say the decomposition wasn't available and answer with the two-point form.

Guardrails specific to first-party demand

Full detail in references/property-demand.md; these are the four that change what an answer is allowed to say.

• Levels never cross sources, only variations do. Area demand counts every property in a radius, first-party demand counts one, sales count a fraction of that one. Never subtract, divide or chart a level from one against a level from another. Within a single source, levels are the hotel's own data and are reported normally.
• Reporting a variation is always allowed; attributing a cause is not. "Searches on your engine fell 19% year over year" is a complete fact and needs nothing else. The moment the sentence becomes "because…", the area control has to be present — without it the number stays true and the explanation doesn't.
• No first-party series and no first-party comparison crosses 2025-01-01 (config/defaults.yaml:property_demand.history_floor). Earlier searches are polluted by scrapers: a different population, not a stronger year.
• Search→booking is a ratio between aggregates, never an attribution. There is no join key between a search and a reservation. Say so whenever a conversion figure appears, and never present it as "this booking came from that search".

Future extensions (not yet implemented)

• Branded HTML/PDF report (reusing sb-revenue-lens/scripts/build_report.py as a base).
• Broader validation of the 9 lenses on other properties, periods and configurations. X1b, X8 and X9 are new and not yet validated on real data — present their output as a reading to check with the hotelier, not as a proven finding, and record what you learn in dev/validation-notes.md.
• Per-night demand pressure (references/property-demand.md §8.2) feeding sb-revenue-lens's L1b and L3 — those are pricing and restriction lenses and belong to that skill, not here. Deferred deliberately: it requires deciding whether first-party demand moves there too, which is a separate conversation.
• Possible consolidation with sb-monday-brief's Detector 1 (see above).

Supporting files