holix-sdd-propose

When to use

User wants a non-trivial feature, API, schema, or product change. Work starts with a specification, not code.

Language (Studio locale)

Match the user's Studio UI language (ru or en only):

• Chat (questions, summaries, progress) — that language only
• All SDD artifacts via sdd_write_artifact (proposal, design, specs, tasks) — that language only
• sdd_update_understanding summary / questions — that language only
• Do not mix languages; do not write specs in the other language
• Structural OpenSpec markers may stay English (## ADDED Requirements, GIVEN/WHEN/THEN), but narrative text, requirement titles, scenarios, and task descriptions must be in the selected locale

If the Studio prompt states locale=ru or locale=en, treat that as authoritative.

Multi-project workspaces

A workspace may contain several projects, each with its own openspec/.

1. sdd_list_projects — pick the project path (empty string = workspace root)
2. Pass project=<path> to every subsequent sdd_* tool for that work

Workflow (propose)

1. sdd_status with project= — if not initialized → sdd_init with the same project=

2. sdd_list_specs + sdd_read_spec for relevant domains. Also read the code, tests, and docs that change would touch — do not ask the user for facts already in the repo

3. sdd_list_changes — avoid duplicate open changes

4. sdd_create_change with slug id and request= (user request text)

5. Understanding gate (if enabled in user prefs — see create_change response).

   Before any clarifying questions to the user, complete this order:

   1. Existing SDD knowledge
      • sdd_list_specs + sdd_read_spec for relevant domains (openspec/specs/)
      • sdd_list_changes with include_archive=true
      • Read related archived change artifacts under openspec/changes/archive/ (proposal, specs, design, tasks) and any overlapping open changes
   2. Project context / /init if needed
      • Read .holix/HOLIX.md (and project-local notes if any)
      • If missing, empty, or insufficient for this request/domain: run project onboarding equivalent to /init for the project path (scan layout + key files; update HOLIX.md via update_holix_section, or ask the user once to run /init <path> if you cannot write). Do not skip when the codebase is unknown.
   3. Assess understanding
      • Call sdd_update_understanding with honest score (0–100) and summary of what you learned from main specs, archives, and HOLIX — before dumping questions at the user
   4. Only then ask residual clarifying questions in chat
      • After each answer: sdd_update_understanding again with user_answer and updated score / questions
      • If score < threshold → keep clarifying (status clarifying)
      • If score ≥ threshold → status ready: offer proceed or more questions
      • If later answers drop score below threshold → new clarifying cycle
   5. Only after user agrees to proceed: sdd_confirm_understanding
   • Do not fill full proposal/specs/tasks until confirmed (or gate disabled/skipped)
   • Do not open with a long questionnaire before steps 1–3

6. Fill artifacts via sdd_write_artifact only (not write_file / inventing paths):

   • proposal → openspec/changes/<id>/proposal.md
   • design → openspec/changes/<id>/design.md
   • tasks → openspec/changes/<id>/tasks.md
   • specs → openspec/changes/<id>/specs/<domain>/spec.md (pass domain= or omit)
   • There is no openspec/changes/<id>/specs.md — do not read_file that path
   • Prefer sdd_status(change_id=…) → artifact_paths before reading anything
   • proposal content — Why / What / Impact
   • specs content — delta with ## ADDED|MODIFIED|REMOVED Requirements and GIVEN/WHEN/THEN. Write each domain with sdd_write_artifact as soon as that domain is drafted. Do not plan every spec file before writing the first one
   • design content — approach + task→assignee table
   • tasks content — checklist with assignees and done_when (see below)
   • No behavior change (refactor, docs, rename): sdd_create_change(..., skip_specs=true) or sdd_write_artifact(..., skip_specs=true). Do not invent requirements. Apply and archive do not demand a delta then