Help choose a diagram type in New Diagram Archify (on hold) #3

New Issue

2026-10-04T10:52:52-07:00

root-at-skic commented

2026-10-04 10:52:52 -07:00

Help the user choose the right diagram type in New Diagram Archify… (added in 0.4.0, #2) when they aren't sure which type fits.

Status: on hold. The approach isn't decided yet.

Original idea

Add a first option to the type picker: "Describe what you want to draw…".
Run archify guide "<description>" --json on what the user types (about 0.05 s).
Reopen the picker with recommendation.type on top, marked Suggested.

Findings (archify 3.0.1, bundled)

archify guide matches specific technical keywords only (matchedSignals). Anything else falls back to architecture with confidence: low. alternatives was empty in every test.

Description	Result
"order status state machine"	lifecycle, high ✓ (signal: state machine)
"ETL pipeline from CRM to warehouse"	dataflow, high ✓ (signals: etl, warehouse)
"API request with Redis cache miss"	sequence, high ✓ (signals: api request, cache miss)
"login sequence diagram"	architecture, low ✗
"approval workflow"	architecture, low ✗
"how orders move from placed to delivered or cancelled"	architecture, low ✗
"plan my summer holiday and hand over work"	architecture, low ✗
"kubernetes deployment"	architecture, low ✗

Built on guide, the feature would mostly suggest nothing useful or the wrong type, especially for everyday descriptions. Not recommended as designed.

Options

Better picker descriptions (small). Add everyday examples under each type so users choose correctly themselves. Examples:
- Sequence: "who calls whom, in order: login, API call, payment"
- Lifecycle: "states something moves through: order status, ticket, application"
- Workflow: "steps of a process: approval, onboarding, release"
- Data Flow: "where data goes: reports, ETL, sync between systems"
- Architecture: "parts of a system and how they connect"
This is a change to TEMPLATES in src/templates.ts only.
Describe and generate (large, separate feature). Use VS Code's Language Model API (vscode.lm) to turn a description into a starter diagram, not just a type.
- Only works for users who have a language-model provider, such as GitHub Copilot.
- Needs validation and retry against archify validate.
Keep guide but only use it when confidence is high. Otherwise show the normal list. Low value given the findings above.

Decision

Pending.

Help the user choose the right diagram type in **New Diagram Archify…** (added in 0.4.0, #2) when they aren't sure which type fits. **Status: on hold. The approach isn't decided yet.** ## Original idea - Add a first option to the type picker: **"Describe what you want to draw…"**. - Run `archify guide "<description>" --json` on what the user types (about 0.05 s). - Reopen the picker with `recommendation.type` on top, marked **Suggested**. ## Findings (archify 3.0.1, bundled) `archify guide` matches specific technical keywords only (`matchedSignals`). Anything else falls back to `architecture` with `confidence: low`. `alternatives` was empty in every test. | Description | Result | |---|---| | "order status state machine" | lifecycle, high ✓ (signal: state machine) | | "ETL pipeline from CRM to warehouse" | dataflow, high ✓ (signals: etl, warehouse) | | "API request with Redis cache miss" | sequence, high ✓ (signals: api request, cache miss) | | "login sequence diagram" | architecture, low ✗ | | "approval workflow" | architecture, low ✗ | | "how orders move from placed to delivered or cancelled" | architecture, low ✗ | | "plan my summer holiday and hand over work" | architecture, low ✗ | | "kubernetes deployment" | architecture, low ✗ | Built on `guide`, the feature would mostly suggest nothing useful or the wrong type, especially for everyday descriptions. **Not recommended as designed.** ## Options 1. **Better picker descriptions (small).** Add everyday examples under each type so users choose correctly themselves. Examples: - **Sequence:** "who calls whom, in order: login, API call, payment" - **Lifecycle:** "states something moves through: order status, ticket, application" - **Workflow:** "steps of a process: approval, onboarding, release" - **Data Flow:** "where data goes: reports, ETL, sync between systems" - **Architecture:** "parts of a system and how they connect" This is a change to `TEMPLATES` in `src/templates.ts` only. 2. **Describe and generate (large, separate feature).** Use VS Code's Language Model API (`vscode.lm`) to turn a description into a starter diagram, not just a type. - Only works for users who have a language-model provider, such as GitHub Copilot. - Needs validation and retry against `archify validate`. 3. **Keep `guide` but only use it when `confidence` is high.** Otherwise show the normal list. Low value given the findings above. ## Decision Pending.

root-at-skic changed title from ~~Suggest a diagram type from a plain-language description~~ to Help choose a diagram type in New Diagram Archify (on hold)

2026-10-04 12:01:19 -07:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vscode-extensions/archify-vscode-ext#3