skills/hindu-succession-calculator/references/conversation-ui.md

# Conversational interface

Present the interview as a calm, mobile-friendly sequence of semantic Markdown cards. ChatGPT controls the surrounding visual style, so use only Markdown that renders reliably. Do not claim that numbered choices are native buttons.

## Experience contract

When the user has not already supplied substantial facts, open with:

## Hindu succession assessment

**What to expect**

- Only questions that can change the inheritance shares
- Usually 6–10 short answers for a straightforward case
- About 3–5 minutes of active time if the facts are known
- A visible stage and updated estimate throughout
- `Not sure` is always acceptable

### Choose how to begin

1. **Fastest:** Tell me everything you know in one message
2. **Guided:** Ask me one step at a time

If the user chooses the fastest route, offer this optional template:

- Deceased and legal sex for succession purposes
- Date and State or Union Territory of death
- Will status
- Properties, ownership, and how each was acquired
- Surviving and predeceased family members

If the opening user message already contains useful facts, do not ask them to choose a mode. Extract the facts, show the compact ledger, and ask only the decisive gaps.

## Progress model

Use these five user-facing stages:

1. Basics
2. Property
3. Family
4. Special checks
5. Review and result

Never use a fixed percentage. The interview branches, so a percentage can become false. Show completed, current, and future stages with text labels and symbols:

`✓ Basics · ● Property · ○ Family · ○ Checks · ○ Result`

Before opening triage is complete, give only the broad straightforward-case estimate from the experience contract. After triage, estimate a range from unresolved decision points, not a single exact number. Use:

**About 4–7 short answers left · 2–4 minutes active time**

Treat time as active answering time when the user knows the facts. Do not give a time estimate when the next step depends on finding a document, resolving a dispute, or obtaining legal advice.

Keep completed stages complete. If an answer opens a new branch, update the remaining range and state the reason in one sentence:

**Estimate updated:** The possible coparcenary interest adds about three property questions.

Do not say `almost done` unless only one mandatory decision point remains.

## Primary question card

Use one primary card per turn. Do not nest cards or surround every sentence with a container. Render it in this order:

### Property details · Stage 2 of 5

`✓ Basics · ● Property · ○ Family · ○ Checks · ○ Result`

**About 4–7 short answers left · 2–4 minutes active time**

**How did the deceased acquire this property?**

1. Purchased or built using personal funds
2. Inherited from family
3. Joint Hindu family or coparcenary property
4. Received by gift or will
5. Not sure

*Why this matters:* The answer determines what interest enters the estate and which succession route applies.

Reply with a number or answer in your own words.

Follow these presentation rules:

- Prefer one decisive question. Ask up to three only when they are short and can be answered together.
- Use numbered choices for mutually exclusive answers and lettered labels for multiple related questions.
- Put `None of these` and `Not sure` last when relevant.
- Use ordinary language first. Put a legal term in parentheses only when useful.
- Keep `Why this matters` to one sentence.
- Use functional symbols sparingly and always pair them with text.
- Avoid decorative emoji, raw HTML, ASCII boxes, fenced code blocks, fake buttons, and dense tables during the interview.
- Accept free text even when choices are shown.

## Fact ledger card

Show the ledger after story-first intake, at stage boundaries, when the user corrects a fact, or before a complex calculation. Do not repeat it after every answer.

### What I have so far

**Confirmed**

- Death: 14 March 2024, Karnataka
- Will: none
- Property: one self-acquired house

**Still needed**

- Whether the deceased's mother was alive

Label assumptions, disputed facts, and unknowns separately when they exist. Invite corrections in one short sentence.

## Early-value cards

Once the statutory route is sufficiently supported, show a short route preview without interrupting the interview:

### Route identified

This is likely a male-intestate Class I route. The spouse, mother, and children may form the first-priority group. Two family facts still control the exact shares.

Do not show speculative fractions. Show a conditional share preview only when the remaining possibilities are finite, clearly stated, and legally safe. Label each scenario and name the one fact that resolves it.

## Finish line

When all mandatory facts are collected, say:

### Ready to calculate · Stage 5 of 5

All required facts have been collected. Please check the summary below. Once confirmed, I can calculate the exact shares.

Then show the fact ledger. After confirmation, present the result using `output-format.md`.