Markdown Syntax Guide

Complete guide to creating surveys using Sibilance's markdown format.

Overview

Sibilance surveys are defined using markdown as the single source of truth. All survey data (flow diagrams, steps, AI instructions) is stored in a structured markdown document that can be version controlled, shared, and edited with any text editor.

Required Structure

Every survey markdown document MUST contain these sections in order:

Title and Description (required)
AI Notes (optional)
Flow Diagram (required)
Steps (required)

1. Title and Description

Start your survey with a level-1 heading (#) for the survey name, followed by optional description text.

markdown

# Survey Name

Optional description text that explains what this survey is for.

Example:

markdown

# Residential Painting Estimate

This survey collects information needed to provide an accurate painting estimate for residential properties.

2. AI Notes (Optional)

The AI Notes section provides behavioral guidance to the AI conducting the survey. This helps ensure the AI speaks in the right tone, handles edge cases appropriately, and uses domain-specific knowledge.

markdown

## AI Notes

- Speak in a friendly, professional tone
- If user seems confused, rephrase the question
- Use the client's first name if they provide it
- Be patient with technical terms (explain if needed)

Purpose:

Guide the AI's conversational style and behavior
Provide context-specific instructions
Set expectations for tone, pacing, and approach
Include domain-specific knowledge or terminology

Format:

Use bullet points or paragraphs
Can include do's and don'ts
Can reference specific steps or scenarios
Keep concise and actionable

Example:

markdown

## AI Notes

**Tone & Style:**
- Professional but warm - you're a painting expert, not a salesperson
- Use homeowner's first name once they provide it
- Be patient with technical terms (explain "popcorn ceiling", "stucco", etc. if needed)

**Pacing:**
- For interior projects: Move quickly through basic questions, slow down on details
- For exterior projects: Weather and HOA questions are critical - don't rush
- If user volunteers information ahead, acknowledge and skip gracefully

**Domain Knowledge:**
- "Popcorn ceiling" = textured ceiling (common in older homes, removal is expensive)
- "Stucco" = cement-based exterior finish (requires special paint)
- "HOA" = Homeowner's Association (may restrict colors)

3. Flow Diagram

The Flow Diagram section defines the survey's conversation flow using a Mermaid flowchart. This visual representation shows how steps connect and where branching logic occurs.

markdown

## Flow Diagram

```mermaid
flowchart TD
    A[Start] --> B{Question}
    B -- Yes --> C[Next Step]
    B -- No --> D[End]


### Flowchart Requirements

**CRITICAL:** The diagram MUST be a **flowchart** (not graph, sequenceDiagram, etc.)

- **Required:** Start with `flowchart TD` (top-down) or `flowchart LR` (left-right)
- **Node IDs:** Must match step IDs defined in the Steps section
- **Connections:** Use `-->` for basic connections, `-- Label -->` for labeled edges
- **Node Shapes:**
  - `[]` for regular nodes (questions, actions)
  - `{}` for decision nodes (branching points)
- **Converging Paths:** Use `&` to merge multiple paths (e.g., `G4 & G5 --> G6`)
- **Comments:** Use `%%` for section comments in the flowchart

### Simple Flow Example

```markdown
## Flow Diagram

```mermaid
flowchart TD
    A[Greeting] --> B{Budget Range}
    B -- Under 5k --> C[Small Project Path]
    B -- Over 5k --> D[Large Project Path]
    C --> E[Get Contact]
    D --> E
    E --> END[End]


### Complex Flow Example

```markdown
## Flow Diagram

```mermaid
flowchart TD
    A[Start: Greeting & Purpose] --> B{Are you the homeowner?}
    B -- Yes --> C[Confirm property address]
    B -- No --> D[Who is the decision maker?]
    D --> E[End call or schedule]
    
    C --> F{Project Type?}
    F -- Interior --> G1[How many rooms?]
    F -- Exterior --> H1[House size?]
    F -- Both --> I1{Start with Interior or Exterior first?}
    I1 -- Interior first --> G1
    I1 -- Exterior first --> H1
    
    %% INTERIOR FLOW
    G1 --> G2[Room types?]
    G2 --> G3{Walls only or ceilings/trim?}
    G3 -- Walls only --> G4[Current wall condition?]
    G3 -- Ceilings + Trim --> G5[Ceiling height? Popcorn?]
    G4 & G5 --> G6{Color change?}
    G6 -- Same color --> G7[Existing paint type?]
    G6 -- Different color --> G8[How many colors per room?]
    G7 & G8 --> G9[Any repairs needed?]
    
    %% EXTERIOR FLOW
    H1 --> H2[Material? Brick / Stucco / Wood / Vinyl?]
    H2 --> H3{Previous paint? When?}
    H3 -- Never / >10 yrs --> H4[Peeling / Mildew?]
    H3 -- <5 yrs --> H5[Same color?]
    H4 & H5 --> H6[Trim / Shutters / Doors?]
    
    %% FINAL PATH
    G9 --> Z[Schedule estimate]
    H6 --> Z
    Z --> END[Thank you!]


## 4. Steps

The Steps section defines each step in the survey. Each step has an ID, label, type, script, and optional notes.

### Step Format

Each step must follow this exact format:

```markdown
### [ID] - [Label]
**Type:** [type]
**Script:** [script text]
**Note:** [optional AI guidance for this step]

Fields:

ID: Single letter (A-Z) or alphanumeric code (A1, B2, etc.) - must match node IDs in flowchart
Label: Human-readable step name
Type: One of: question, decision, action, end
Script: The text that will be read aloud to users (should be natural and conversational)
Note: (Optional) AI guidance notes specific to this step

Step Types

question: Asks the user for information
decision: A branching point based on user response
action: Makes a statement or provides information
end: Concludes the survey

Step Examples

markdown

## Steps

### A - Start: Greeting & Purpose
**Type:** question
**Script:** Hi, this is [Your Name] with [Company]. I'm calling to gather details for your painting estimate. Is this a good time?

### B - Are you the homeowner?
**Type:** decision
**Script:** Great! Are you the homeowner or decision maker?

### C - Confirm property address
**Type:** question
**Script:** Perfect. Can you confirm the property address for me?

### G1 - How many rooms?
**Type:** question
**Script:** How many rooms are we painting?

### G3 - Walls only or ceilings/trim?
**Type:** decision
**Script:** For each room, are we doing walls only, or walls plus ceilings and trim?

### Z1 - Send prep email
**Type:** action
**Script:** Perfect! I'll send you a confirmation email with what to have ready, like furniture access, HOA documents, and color samples if you have them.

### END - End Call: Thank you!
**Type:** end
**Script:** Thank you so much for your time! We'll see you on [date/time]. Have a great day!

Step Notes

Step-level notes provide AI guidance for handling specific scenarios:

markdown

### E - Get Contact
**Type:** question
**Script:** What's the best phone number to reach you?
**Note:** If user hesitates, reassure them this is just for scheduling

Complete Example

Here's a complete survey example:

markdown

# Budget Qualifier

Quick budget check for painting projects

## AI Notes

- Keep the conversation brief and friendly
- If user hesitates on budget, reassure them that ranges are fine
- Use conversational numbers (e.g., "five thousand" not "$5,000")

## Flow Diagram

```mermaid
flowchart TD
    A[Greeting] --> B{Budget Range}
    B -- Under 5k --> C[Small Project Path]
    B -- Over 5k --> D[Large Project Path]
    C --> E[Get Contact]
    D --> E
    E --> END[End]


## Steps

### A - Greeting
**Type:** question
**Script:** Hi! Thanks for your interest. I just need to ask a few quick questions to help us give you an accurate quote.

### B - Budget Range
**Type:** decision
**Script:** What's your budget range for this project? Under $5,000 or over $5,000?

### C - Small Project Path
**Type:** action
**Script:** Perfect! For projects in this range, we can usually start within 2 weeks.

### D - Large Project Path
**Type:** action
**Script:** Great! For larger projects, we'll need to schedule an in-person consultation.

### E - Get Contact
**Type:** question
**Script:** What's the best phone number to reach you?
**Note:** If user hesitates, reassure them this is just for scheduling

### END - End
**Type:** end
**Script:** Thank you! We'll be in touch soon.

Best Practices

Writing Scripts

Be Conversational: Write scripts as if speaking naturally, not reading a form
Keep It Brief: Long scripts can overwhelm users - break complex questions into multiple steps
Use Natural Language: Avoid jargon unless necessary, and explain technical terms
Provide Context: Help users understand why you're asking
Be Flexible: Scripts are guidelines - the AI will adapt based on user responses

Good:

markdown

**Script:** What's your budget range for this project? Under $5,000 or over $5,000?

Bad:

markdown

**Script:** Please provide your budget range. Select one: Under $5,000 or Over $5,000.

Naming Steps

Use Descriptive Labels: Make it clear what each step does
Use Consistent IDs: Follow a pattern (A, B, C or G1, G2, G3 for grouped steps)
Group Related Steps: Use prefixes like G1, G2 for interior flow, H1, H2 for exterior flow

Flowchart Design

Keep It Readable: Use comments (%%) to organize complex flows
Use Labels: Label edges to show decision paths clearly
Merge Paths: Use & to show where multiple paths converge
Test Flow: Ensure all paths lead to an end step

AI Notes

Be Specific: Provide concrete guidance, not vague instructions
Include Domain Knowledge: Help the AI understand industry-specific terms
Handle Edge Cases: Guide the AI on what to do when things go wrong
Set Tone: Define the personality and style you want

Validation

The Sibilance parser validates:

✅ Presence of ## Flow Diagram section
✅ Presence of ## Steps section
✅ Valid mermaid code block with content
✅ At least one step defined
✅ Each step has ID, label, type, and script
✅ Step format matches: ### [ID] - [Label]\n**Type:** [type]\n**Script:** [script]
✅ Step IDs in flowchart match step IDs in Steps section
✅ Optional ## AI Notes section (if present, extracted but not validated for content)

Survey Builder - Visual survey builder
Markdown Workflows Recipe - Advanced markdown patterns
Survey Integration - Integrating surveys into your app

Markdown Syntax Guide ​

Overview ​

Required Structure ​

1. Title and Description ​

2. AI Notes (Optional) ​

3. Flow Diagram ​

Step Types ​

Step Examples ​

Step Notes ​

Complete Example ​

Best Practices ​

Writing Scripts ​

Naming Steps ​

Flowchart Design ​

AI Notes ​

Validation ​

Related ​

Markdown Syntax Guide

Overview

Required Structure

1. Title and Description

2. AI Notes (Optional)

3. Flow Diagram

Step Types

Step Examples

Step Notes

Complete Example

Best Practices

Writing Scripts

Naming Steps

Flowchart Design

AI Notes

Validation

Related