Projects › Discovery & Scoping
Watch the demo (AI-narrated, 1:20)
Narrated with a generated voice; captions included.
A scroll through the discovery pack: six stakeholder sessions, the four-check test that picked the order, and pricing built on measured costs.
Read the narration
Before I wrote any code for this hotel group,
I spent a day just asking questions.
This repo is what came out of that.
It's a simulated client, with synthetic data.
I talked to six people.
The general manager, the front-desk lead, activities, revenue, IT, and a guest.
The front-desk lead told me a guest waited four minutes while they radioed a manager about one fee.
That one answer shaped the first stage.
I scored six ideas,
then ran a four-check test.
Has someone felt it, would someone pay, can I build a first version in a week, and do I know the first user.
Automatic refunds failed.
The manager said that's exactly what would make them switch it off.
Here's the pricing.
The only measured input is the model cost:
eighteen cents per thousand questions, and about a dollar twenty-four per thousand emails.
Everything else is an assumption,
so it's a range, not a promise.
The point is the order.
Staff-facing before guests,
read-only before anything that writes.
Every later stage links back here, and the links are in the README.
Discovery & Scoping
Before any code: six stakeholder sessions, six candidate use cases scored with a four-check test, a statement of work, a pricing model built on measured costs, and the security answers a procurement team asks for.
Independent project: a simulated client engagement. The people and their answers are fictional and written to match the synthetic documents of the later stages. It was written after stages 1–5 were built, so it explains their order rather than predicting it.
A document pack, nothing to host: Markdown documents plus a tested pricing script, read on GitHub. That's why its badge says Published, not Live.
Problem
A hotel group wanted AI help at the front desk but hadn't agreed what to build first, what it could touch, or what it should cost. The front-desk lead described a guest waiting four minutes while they radioed a manager about one fee. The GM was clear: one confident wrong answer about money reaching a guest, and it gets switched off.
Approach
- Discovery: 10–15 questions each for the GM, front-desk lead, activities manager, revenue manager, IT/security and a guest, ending in users, success metrics, data sensitivity, constraints and open questions.
- Problem selection: six use cases scored on value, feasibility, risk and data readiness, then a four-check test: someone has felt the problem, someone would pay, a first version is buildable in a week, the first user is known.
- Scope and price: a statement of work with acceptance criteria per stage, and a pricing script whose only measured inputs are the model costs from the later stages' release runs.
- Security: answers to an 18-question procurement questionnaire and a risk register, each pointing at what was actually built; anything not built is marked roadmap.
Architecture
- Staff in a browser: front desk, reservations, managerEach role uses only the app it needs.
- Three apps, one container eachKnowledge Assistant (stage 1), Guest Request Agent (stage 2), Ops Analytics (stage 8); each calls Claude Haiku 5.5.
- Stage 7 tool server (MCP), with roles and an audit log
search_policy,lookup_booking, credit and booking requests; the Guest Request Agent goes through it. - DataPolicy documents per property feed a search index (BM25 plus optional embeddings); bookings come from a read-only export.
- Every app and the tool server write a redacted request log (Postgres, 30 days).
- Stage 3's eval harness gates every change in CI.
docs/ARCHITECTURE_PROPOSAL.md. Stages 1–8 then built it.A real output
Use case A · Knowledge assistant
Someone has felt the problem: yes, the front-desk lead's 4-minute radio call. Someone would pay: yes, the GM owns the pilot budget. V1 buildable in a week: yes. First customer known: yes, the Mountain Lodge front desk. Pass.
From docs/PROBLEM_SELECTION.md: six use cases scored the same way; four passed (A, B, D, E) and became stages 1, 2, 7 and 8.
What came out of it
| Use case | Result |
|---|---|
| Policy knowledge assistant | Pass (built as stage 1) |
| Guest email agent | Pass (stage 2) |
| Tools with roles and audit (MCP) | Pass as an enabler (stage 7) |
| Revenue questions + anomaly alerts | Pass (stage 8) |
| Guest activities concierge | Not yet: data needs cleaning, no property agreed to a guest pilot |
| Automatic refunds and upgrades | Fail: the GM would switch it off |
Two rules set the order: staff-facing before guest-facing, and read-only before anything that writes.
Pricing, from measured costs
The pricing script uses two measured inputs: $0.18 per 1,000 questions (stage 1, v1.6.0 release run) and $1.24 per 1,000 emails (stage 2, v1.1.0). Everything else is an assumption, shown as pessimistic / base / optimistic. The lesson in the numbers: model tokens are a few dollars a month for two properties, so support time, not tokens, is what a price has to track. All prices are projections, not quotes.
Engineering
- Docs that can't drift: the pricing tables are written by the script, and a test fails if the document and the script disagree.
- Checks: 25 tests; a doc check for required documents, broken links and placeholders; CI with ruff, pip-audit, gitleaks, markdownlint and a link check.
Limitations
- The answers are simulated. A real engagement would replace them with notes from real sessions.
- Written after stages 1–5, so the selection explains an order that was already built.
- Pricing assumptions (support hours, rate, hosting) are not measured; a pilot's time log and invoices would replace them.
- Roadmap: SSO, region pinning and a third-party pen test are marked as such in the security answers.
What's next
- Replace the simulated answers with notes from real sessions in a real engagement
- Replace pricing assumptions with a pilot's time log and invoices