| name | equipment-gap-questionnaire |
| description | This skill should be used when the user asks to "fill gaps in equipment survey", "complete the equipment survey", "interview building operator", "questionnaire for building systems", or wants to gather missing equipment details through interactive Q&A. Analyzes existing building system data from local documents, identifies gaps relative to Audette's equipment survey schema, and conducts a conversational interview with a building operator to collect missing information until the survey is 100% complete.
|
| version | 1.0.0 |
Equipment Gap Questionnaire
Conduct an interactive questionnaire with building operators to fill gaps in equipment
survey data. This skill extracts available system information from local documents, identifies
what's missing compared to Audette's equipment survey schema, and interviews the operator
using natural language Q&A until all required fields are complete.
Required MCP Connections
| MCP | Tools used | If disconnected |
|---|
| Audette | get_building_model_details, get_equipment_survey, submit_equipment_survey | Cannot proceed — ask user to reconnect |
No other MCPs required - Uses local file reading (Read tool) for document extraction.
Workflow Overview
1. Extract available data from documents/existing survey
2. Identify gaps relative to equipment-schema.md
3. Interview operator using AskUserQuestion
4. Parse natural language responses → map to schema fields
5. Ask follow-up questions for incomplete sections
6. Repeat until survey is 100% complete
7. Confirm final survey with operator
8. Submit to Audette
Pre-flight
Call switch_customer_account with the Audette customer account UID from the system prompt.
This is required before any Audette write operations — omitting it causes HTTP 401.
If no account UID is in the system prompt, call list_customer_accounts and ask the user to select one.
Step 1: Identify Building
The building UID is in the system prompt if this asset has been linked to Audette.
If not, call list_buildings to find it by name or address, or ask the user directly.
You need the building_model_uid — verify it exists by calling get_building_model_details.
Step 2: Gather Available Equipment Data
2a. Check for Existing Survey
Call get_equipment_survey with the building_model_uid. If a survey exists, load it
as the starting point. Note which fields are already populated vs. null.
2b. Extract from Documents (Optional)
If project documents are available, use Grep/Read to search for system descriptions.
Use Glob to find relevant documents:
**/*.pdf
**/PCA*.pdf
**/CNA*.pdf
**/*equipment*.pdf
**/*mechanical*.pdf
Use Grep with search patterns:
| System | Search Pattern (case-insensitive) |
|---|
| Heating | boiler|furnace|heat pump|heating system|HVAC|BTU|MMBH |
| Cooling | chiller|air condition|cooling|DX|tons|SEER |
| DHW | domestic hot water|DHW|water heater|gallon |
| Ventilation | ventilation|air handling|AHU|makeup air|ERV|HRV|CFM |
| Lighting | lighting|LED|fluorescent|lamp|fixture|occupancy sensor |
| Elevators | elevator|lift|hydraulic|traction |
| Renewables | solar|photovoltaic|PV|renewable|battery |
When Grep finds matches: Use Read to get the surrounding context (pages/sections).
Extract specifications like capacity, efficiency, fuel type, installation dates.
Aggregate findings into notes about each system category.
2c. Load Equipment Schema
Read the equipment schema from the audette-equipment-survey skill:
skills/audette-equipment-survey/references/equipment-schema.md
This contains all sections, fields, valid enum values, and field descriptions you'll need
for gap analysis and question generation.
Step 3: Perform Gap Analysis
For each major equipment section in the schema, determine its completeness:
| Section | Status Logic |
|---|
| Complete | _exists field is set AND all required fields for that system are populated |
| Partially complete | _exists = true but some fields are null |
| Unknown | _exists field is null (don't know if system exists) |
| Not applicable | _exists = false (system doesn't exist in building) |
Critical vs. Optional Fields
Critical fields (required if _exists = true):
*_type (equipment type enum)*_size or *_capacity (impacts carbon model significantly)*_average_installation_year (determines remaining useful life)
Optional but helpful fields:
*_heating_type, *_cooling_type (refines model)*_terminal_units (distribution method)*_count (for elevators, rooftop units)
Gap Prioritization
Organize gaps into:
- Critical unknowns:
_exists is null (don't know if system exists)
- High priority:
_exists = true but type or size missing
- Medium priority: Installation year, efficiency details missing
- Low priority: Secondary characteristics missing
Step 4: Generate Targeted Questions
For each gap, generate a natural language question appropriate for a building operator.
Read references/question-templates.md now — it contains example questions for each
equipment section, accounting for typical operator responses.
Question Design Principles
DO:
- Use plain language, not technical jargon (unless operator is highly technical)
- Ask about observable equipment ("What type of boilers do you have?")
- Accept ranges and estimates ("About how old are the boilers? Best guess is fine.")
- Ask for counts and sizes together ("How many chillers, and what's the capacity?")
- Provide examples in parentheses ("Natural gas, electric, oil, or other?")
DON'T:
- Ask for exact enum values (operator won't know "condensing_gas_boiler" enum)
- Require precision when estimates work (installation year ±2 years is fine)
- Use acronyms without explanation (say "domestic hot water" not just "DHW")
- Ask multiple unrelated questions in one (break into separate questions)
Example Question Transformations
| Schema Field | Bad Question | Good Question |
|---|
central_plant_heater_type | "What's the central_plant_heater_type enum value?" | "What type of heating system serves the building? (Boiler, furnace, heat pump, or other?)" |
central_plant_heater_size | "What's the heater size in kW?" | "What's the total heating capacity? (Can be in MBH, BTU/hr, kW, or tons — I'll convert to tons)" |
air_handling_equipment_exists | "Does air_handling_equipment_exists = true?" | "Is there a central air handling unit or ventilation system?" |
Step 5: Conduct Interactive Interview
Use AskUserQuestion to interview the building operator. Work through gaps in priority
order (critical → high → medium → low).
Interview Flow
-
Start with critical unknowns (whether systems exist)
- "Does the building have a central heating system, or is heating suite-level?"
- "Is there a central chiller or cooling system?"
-
For confirmed systems, gather details
- "You mentioned a central boiler. What type? (Gas, electric, oil?)"
- "How many boilers are there, and what's the capacity of each?"
- "About how old are the boilers? Even a rough estimate helps."
-
Parse responses and map to schema
-
Ask follow-ups for ambiguity
- Response: "Gas boilers"
- Follow-up: "Are these condensing boilers (high-efficiency, AFUE ≥90%) or standard boilers?"
-
Confirm and move to next gap
- "Got it — 2 standard gas boilers, 500 MBH each, installed around 2005. Now, about the
cooling system..."
Handling Natural Language Responses
Building operators will respond conversationally. Parse key information:
| Operator Response | Extract |
|---|
| "2 boilers, 500 MBH each" | Count: 2, Size per unit: 500 MBH → Total: 1000 MBH ÷ 12 = 83.3 tons |
| "Old gas boiler, maybe 1995" | Type: gas_boiler, Installation year: 1995 |
| "We have Carrier rooftop units on each floor, probably 15 total, 5 ton each" | Type: split_system_air_conditioner (likely), Count: 15, Size per unit: 5 tons → Total: 75 tons |
| "Hot water is in each suite, electric" | central_distribution: false, Type: electric_storage |
| "No chiller, just window ACs" | central_plant_cooler_exists: false |
Clarification Strategy
When responses are ambiguous:
If manufacturer/model mentioned: Use it to infer type
- "Weil-McLain" → likely standard gas boiler (not condensing)
- "Navien" → likely condensing gas boiler or tankless water heater
- "Carrier" → could be rooftop unit or split system (ask follow-up)
If capacity units unclear: Ask for clarification
- "500" → "Is that 500 MBH, 500 kW, or 500 BTU/hr?"
If age is vague: Accept estimates
- "Pretty old" → "Best guess — installed in the 1990s, 2000s, or earlier?"
If distribution method unclear:
- "How is heat distributed? Radiators, baseboard, forced air, or something else?"
Step 6: Validate Completeness
After each section, verify all required fields are populated.
Completeness Checklist
For each section where _exists = true, confirm:
Handle Edge Cases
Multiple systems of different types:
- If building has 2 boilers + 1 heat pump, ask: "Which is the primary heating system?"
or "Do boilers handle majority of the load, or heat pump?"
- Survey schema expects one primary system per section. If truly hybrid, document in notes
and choose the dominant system for the survey.
Partial retrofits:
- If half the building has new equipment and half has old: "What year was the most recent
equipment installed? We'll use that as the average."
Unknown details:
- If operator genuinely doesn't know (e.g., "Not sure about chiller capacity"), note it:
- Option 1: Estimate based on building size (e.g., "For a 50,000 SF building, typical
chiller is 150-200 tons. Does that sound right?")
- Option 2: Mark for site visit / nameplate verification
Step 7: Review and Confirm
Once all gaps are filled, present the complete survey back to the operator for confirmation.
Confirmation Format
## Equipment Survey Summary
I've gathered the following information. Please review and confirm before I submit to Audette:
### Heating System ✓
- **Type:** Gas boiler (standard, non-condensing)
- **Capacity:** 83.3 tons (1,000 MBH total — two 500 MBH boilers)
- **Distribution:** Hydronic baseboard radiators
- **Installation Year:** 2005
### Cooling System ✓
- **Type:** Rooftop units (split system air conditioners)
- **Capacity:** 75 tons (15 units @ 5 tons each)
- **Installation Year:** 2010
### Domestic Hot Water ✓
- **Configuration:** Suite-level (not centrally distributed)
- **Type:** Electric storage water heaters
- **Capacity:** 4.5 kW element rating ÷ 3.517 = **1.28 tons** per unit (50 gal tank; nameplate rating used directly — if only tank volume had been known, the fallback rule of thumb `gallons ÷ 40` would give ≈1.25 tons, consistent with the nameplate figure here)
- **Installation Year:** 2015
[... continue for all sections ...]
**Does this look correct? Any changes needed before I submit?**
If operator identifies errors or additions, revise the affected sections and re-confirm.
Step 8: Submit to Audette
Once confirmed, call submit_equipment_survey with the complete survey payload.
Submission Format
Build the JSON payload according to the equipment schema. All top-level sections must be
present. For sections where equipment doesn't exist, set _exists: false and all other
fields to null.
Example payload structure:
{
"building_model_uid": "abc-123-def",
"air_handling_equipment": {
"air_handling_equipment_exists": true,
"air_handling_equipment_type": "packaged_air_handling_unit",
"air_handling_equipment_heating_type": "hydronic",
"air_handling_equipment_cooling_type": "direct_expansion",
"air_handling_equipment_supply_air_rate": 12000.0,
"air_handling_equipment_average_installation_year": 2008
},
"central_plant_cooler": {
"central_plant_cooler_exists": false,
"central_plant_cooler_type": null,
"central_plant_cooler_terminal_units": null,
"central_plant_cooler_size":
... all other sections
After submission, inform the operator that the survey is complete and carbon modeling will
be re-run automatically.
Important Rules
Parsing Natural Language
- Be generous with interpretation: "Old gas boilers" → infer
gas_boiler type
- Confirm assumptions: "I'm assuming these are standard gas boilers, not condensing.
Correct?"
- Handle units gracefully: Convert MBH, BTU/hr, or kW to ton-equivalents for every heating/cooling/DHW size field — never submit kW or gallons/litres for these fields
- Accept estimates: Installation year ±2 years is fine, capacity ±10% is fine
Unit Conversions
Keep these conversions ready:
| From | To | Formula |
|---|
| MBH (1000 BTU/hr) | tons | MBH ÷ 12 |
| BTU/hr | tons | BTU/hr ÷ 12,000 |
| kW | tons | kW ÷ 3.517 |
| Gallons | Litres | Gallons × 3.785 (tank volume only — not a capacity conversion) |
All heating, cooling, and DHW capacity sizes (central_plant_cooler_size, central_plant_heater_size, central_plant_heat_pump_size, terminal_cooler_size, terminal_heater_size, terminal_heater_cooler_size, heat_pump_size, domestic_hot_water_heater_size) must be submitted as ton-equivalents — never kW, never litres/gallons. Per Christopher (2026-07-16): "all heating cooling and DHW size must be converted to ton equivalents." A DHW heater's thermal/recovery rating converts to tons the same way as any other heating capacity, and is preferred whenever documented. Rule of thumb when only tank volume is known: tons ≈ gallons ÷ 40 (litres ÷ 151) — based on typical storage water heater sizing (~4.5 kW element per 40–50 gal tank ≈ 1 ton per ~40 gal). Flag when this fallback was used instead of a documented nameplate rating.
Enum Mapping
Read references/enum-mapping.md for common operator terms → schema enum mappings.
When operator says "gas boiler," infer:
- If they mention "high efficiency" or "condensing" →
condensing_gas_boiler
- Otherwise →
gas_boiler (standard)
- If unsure, ask: "Is this a condensing boiler (AFUE ≥90%)?"
Never Invent Data
If operator doesn't know something and can't estimate:
- Mark it in notes: "Chiller capacity unknown — requires site visit for nameplate"
- Set field to
null in submission
- Inform user which fields are still missing
When to Use This Skill vs. Other Skills
Use equipment-gap-questionnaire when:
- Documents don't provide enough detail to complete survey
- User wants to interview building operator to fill gaps
- Existing survey is partially complete and needs finishing
- Interactive Q&A is preferred over manual form-filling
Use audette-equipment-survey when:
- Complete equipment data is already in documents (PCNA, CNA, etc.)
- No operator interview needed
- Extracting and submitting in one shot
Use system-details when:
- User wants a comprehensive overview (not submitting to Audette)
- Preparing for a meeting or review
- Synthesis-oriented, not submission-oriented
Additional Resources
Reference Files
For question templates and enum mapping:
references/question-templates.md - Example questions for each equipment section,
handling typical operator responsesreferences/enum-mapping.md - Common operator terminology mapped to schema enum values
The equipment schema itself lives in the audette-equipment-survey skill and should be
loaded from there:
skills/audette-equipment-survey/references/equipment-schema.md
