From 0525364eda82000c7c5654e48fb1aba9e74eddd1 Mon Sep 17 00:00:00 2001 From: abhiram-vad Date: Mon, 3 Aug 2026 09:42:21 -0700 Subject: [PATCH 01/17] =?UTF-8?q?feat(planner):=20grow=20the=20case=20SDD?= =?UTF-8?q?=20authoring=20engine=20=E2=80=94=20sole-author=20migration=20(?= =?UTF-8?q?1/4)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Planner becomes the sole case-SDD author. Adds the conversational case design lane (Listen/Sketch/one Case Review confirmation) with three entry modes (delegated SDD-only from uipath-maestro-case, direct design, draft finalization), full design-time tenant resolution (registry pull, cache lookups, connections, ambiguity/empty gate at review time), the case authoring rules (ported from maestro-case sdd-generation-rules), worked I/O examples, and the blueprint-shaped case SDD template carried forward from #2305 with the Testing/NFR un-nesting fix. Delegated mode renders SDD text in memory and hands back — the caller owns the write. Co-Authored-By: Claude Fable 5 --- .../references/phase-0-interview.md | 271 ----- skills/uipath-planner/SKILL.md | 26 +- .../assets/templates/case-sdd-examples.md | 532 +++++++++ .../assets/templates/case-sdd-template.md | 571 +++++---- .../references/case-authoring-rules-guide.md | 1016 +++++++++++++++++ .../references/case-design-lane-guide.md | 264 +++++ .../references/package-selection-guide.md | 4 +- .../references/pdd-driven-lane-guide.md | 8 +- .../references/product-selection-guide.md | 4 +- .../references/sdd-generation-guide.md | 31 +- .../check_procurement_sla_interrupts.py | 0 .../procurement_sla_interrupts.yaml | 0 .../candidate_interview.yaml | 0 .../check_candidate_interview.py | 0 .../check_loan_origination.py | 0 .../case_design_loan}/loan_origination.yaml | 0 .../check_resource_name_contract.py | 0 .../finalize_from_draft.yaml | 0 .../fixtures/sdd.draft.md | 0 .../finalize_from_draft_loan.yaml | 0 .../fixtures/sdd.draft.md | 0 .../check_picker_pairing.py | 0 .../finalize_picker_pairing.yaml | 0 .../fixtures/sdd.draft.md | 0 .../check_reject_route.py | 0 .../finalize_reject_route.yaml | 0 .../fixtures/sdd.draft.md | 0 27 files changed, 2120 insertions(+), 607 deletions(-) delete mode 100644 skills/uipath-maestro-case/references/phase-0-interview.md create mode 100644 skills/uipath-planner/assets/templates/case-sdd-examples.md create mode 100644 skills/uipath-planner/references/case-authoring-rules-guide.md create mode 100644 skills/uipath-planner/references/case-design-lane-guide.md rename tests/tasks/uipath-maestro-case/{phase_0_to_case/procurement_sla_interrupts => design_delegation_procurement}/check_procurement_sla_interrupts.py (100%) rename tests/tasks/uipath-maestro-case/{phase_0_to_case/procurement_sla_interrupts => design_delegation_procurement}/procurement_sla_interrupts.yaml (100%) rename tests/tasks/{uipath-maestro-case/phase_0_to_case/candidate_interview => uipath-planner/case_design_interview}/candidate_interview.yaml (100%) rename tests/tasks/{uipath-maestro-case/phase_0_to_case/candidate_interview => uipath-planner/case_design_interview}/check_candidate_interview.py (100%) rename tests/tasks/{uipath-maestro-case/phase_0_to_case/loan_origination => uipath-planner/case_design_loan}/check_loan_origination.py (100%) rename tests/tasks/{uipath-maestro-case/phase_0_to_case/loan_origination => uipath-planner/case_design_loan}/loan_origination.yaml (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft => uipath-planner/case_finalize_draft}/check_resource_name_contract.py (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft => uipath-planner/case_finalize_draft}/finalize_from_draft.yaml (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft => uipath-planner/case_finalize_draft}/fixtures/sdd.draft.md (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_loan => uipath-planner/case_finalize_draft_loan}/finalize_from_draft_loan.yaml (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_loan => uipath-planner/case_finalize_draft_loan}/fixtures/sdd.draft.md (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_picker => uipath-planner/case_finalize_draft_picker}/check_picker_pairing.py (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_picker => uipath-planner/case_finalize_draft_picker}/finalize_picker_pairing.yaml (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_picker => uipath-planner/case_finalize_draft_picker}/fixtures/sdd.draft.md (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_reject => uipath-planner/case_finalize_draft_reject}/check_reject_route.py (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_reject => uipath-planner/case_finalize_draft_reject}/finalize_reject_route.yaml (100%) rename tests/tasks/{uipath-maestro-case/phase_0_finalize_draft_reject => uipath-planner/case_finalize_draft_reject}/fixtures/sdd.draft.md (100%) diff --git a/skills/uipath-maestro-case/references/phase-0-interview.md b/skills/uipath-maestro-case/references/phase-0-interview.md deleted file mode 100644 index b3eb92fdbf..0000000000 --- a/skills/uipath-maestro-case/references/phase-0-interview.md +++ /dev/null @@ -1,271 +0,0 @@ -# Phase 0 — Interview Mode (case design) - -This file is a **thinking guide** for the agent: how to listen, assume, confirm once, and hand off fast when no `sdd.md` is provided. Phase 0 designs the case in the session's **in-memory model**; `sdd.md` is rendered from that model in parallel with the first build actions — a reference artifact, never a review gate. - -> **Authoritative for the interview path only.** Trigger detection, mode behavior, confirmation, resumption, output contract. **Content rules** (authority hierarchy, task-type override priority, render-required fields, variable lineage, review items, source ledger) live in [sdd-generation-rules.md](sdd-generation-rules.md). Phase 1 logic lives in [planning.md](planning.md). Phases 2–6 live in [phased-execution.md](phased-execution.md). - -## Goal - -Design the case as an in-memory model shaped by [`assets/templates/sdd-template.md`](../assets/templates/sdd-template.md), confirm it in ONE user prompt, then start the build. Phase 0 is **best-assumption by default**: it decides everything it can from the user's words and documents, and *informs* the user of every decision — it does not interrogate. `sdd.md` renders from the confirmed model concurrently with the first build actions. For later sessions and re-runs the file is the contract (Rule 2: trust as written); within this session, the in-memory model that produced it drives the build. - -**The Phase 0 confirmation IS the plan-first approval surface.** If workspace or project rules require "show a plan before editing," satisfy that requirement by showing the structured §Confirm case-design summary below. Do not insert a separate generic implementation plan, "Build Plan," or "Approve this plan" checkpoint before §Confirm. A user "Yes" to a generic implementation plan is not a Build answer and must not create files. - -Phase 0 writes: - -- `sdd.md` — rendered once from the confirmed model, batched with the first build actions (or written and reported when the request was design-only). -- `sdd-viewer.html` — optional, generated only on explicit request (§HTML preview). -- `sdd.draft.md` — ONLY when the user explicitly asks for a draft to review; normal runs never create it. If the request explicitly says to get/save the draft and stop, show the Case Review and write the draft in the same response instead of asking for another approval. `tasks/registry-resolved.json` is a Phase 1 artifact — Phase 0 does not write it. - -**Fast path — no-build design + plan.** If the opening request explicitly asks to produce `sdd.md` plus `tasks/tasks.md` and stop before `caseplan.json`, follow §Build start's **No-build design + plan request** path immediately after sketching the case. This path is self-contained: do not read `planning.md`, plugin planning references, tenant registry/cache files, or the full `sdd-generation-rules.md` checklist. Read this file plus `assets/templates/sdd-template.md` only as needed, compose a concise full-template SDD, write `sdd.md`, create `tasks/`, write the compact plan, and stop. Keep the artifacts bounded: one short rationale paragraph per stage/task/SLA/exception choice is enough; do not expand optional examples, source-ledger prose, registry audit detail, or build-phase validation notes. - -## When Phase 0 runs - -Strict binary trigger. Look for an `.md` file at the resolved path whose basename (case-insensitive) contains `sdd`. Examples that count: `sdd.md`, `loan-sdd.md`, `case_demo_sdd.md`, `./specs/onboarding-sdd.md`. Plain `.md` references without `sdd` in the name don't count. - -| State | Action | -|---|---| -| File present, basename = `sdd.md` | Skip Phase 0. Hand to Phase 1. | -| File present, basename ≠ `sdd.md` | Copy contents to `./sdd.md` (preserve original at its path). Skip Phase 0. Hand to Phase 1. | -| File absent, `sdd.draft.md` present | Resume (§Resumption). | -| File absent, no draft | Run Phase 0 from scratch (§Entry). | - -If the user prompt names no `.md` reference, default candidate is `./sdd.md` — proceed on that assumption and record it as a decision; do not ask. - -## Entry - -**If the user's request already describes the case** (any stages, work, trigger, domain, or attached docs), skip every entry prompt: print the roadmap from `SKILL.md § User-facing roadmap` and go straight to work — the request IS the first Listen input. **Only a bare request** ("create a case" with nothing else) gets the Listen opener after the roadmap. There is no entry menu; a user who has an `sdd.md` will say so, and abort is always a free-text away. If the same request also asks for `tasks.md`, do not read planning/plugin references yet; first show the Phase 0 Case Review and get the Build / Save approval. - -**No tenant work at Entry.** Nothing about the tenant is a prerequisite for designing the case — do not run login or `registry pull` up front. Grounding starts only when the case shows it needs it (§Tenant grounding). - -## Tenant grounding — requirement-driven, one light pass, no questions - -Phase 0 grounds resources lazily, in parallel with the design, with a **single name-match pass** at most. Schema discovery (`tasks describe`, `case spec`) belongs to the build phases — never run it in Phase 0. - -1. **Intake batch.** Read every supplied document in parallel. Extract named systems, resources, likely tasks, and roles. -2. **Requirement-driven kickoff.** For build runs only, the FIRST moment the sketch identifies tenant-bound work — a named system/resource/connector, or an inferred runnable/connector/action task — start the grounding chain as ONE background command, in the same batch as whatever is already running: `uip login status --output json && uip maestro case registry pull`. It resolves while sketching continues; a case with no tenant-bound items never pulls in Phase 0. Best-effort: never block on it, never surface its output unprompted; on failure, one plain-language line (§What to say while working), keep intended names, mark identities `resolve at build`, continue. If the harness cannot run background commands, run login → pull in the batch that composes the confirmation. **No-build runs skip grounding:** when the user explicitly asks to stop at a draft, final SDD, or implementation plan and not create `caseplan.json`, do not run login, registry, connection, schema, or user-discovery commands in Phase 0; preserve concrete intended names and mark identities `resolve at build`. -3. **Light match pass — join, never wait.** When composing the confirmation, check the chain. If the pull succeeded, run ONE cache lookup per named or inferred resource (`~/.uip/case-resources/-index.json`; `action-apps-index.json` for HITL apps; `typecache-activities-index.json` / `typecache-triggers-index.json` for connectors) — all lookups in one parallel batch. With ≥ 4 lookups, use parallel read-only workers where supported (one per item or type family; cache reads only — never writes, never prompts, never login/pull; parent spot-verifies adopted identities). Bucket each result: - - **Single confident match** (1 match across all folders, ≥ 1 shared name token) → adopt silently; shows as the task's resource in the confirmation with a decision line. - - **Anything else** (multiple matches, cross-folder same-name, no token overlap, zero matches, 0 or > 1 enabled connections for a connector) → mark `resolve at build`. Do NOT ask, do NOT auto-pick among candidates, do NOT fetch schemas. Phase 1's discovery and its Rule 17 gate handle the choice with full authority. - - If the pull has NOT finished when the confirmation is ready, do not wait: present with `resolve at build` on the tenant-bound items and let the build reconcile — the confirmation is never delayed by the tenant. - -**Guardrails:** registry data is evidence, not requirements — never add/rename business work to match tenant inventory; never dump catalogs; keep type-specific portable names concrete (`Resolved Resource`, Action App title, `Child Case`) even when identity defers; a connector with zero connections is `resolve at build`, not a reason to change the task type. A no-build run does not need tenant evidence to be useful; the later build run owns authoritative identity resolution. - -## Modes - -Three moves. **Listen** takes in everything offered; **Sketch** builds the complete case model by best assumption, recording every decision; **Confirm** shows the whole case once with the decisions taken and asks a single question — on a Build answer, the build starts and `sdd.md` is written alongside it (§Build start). Listen and Sketch loop freely as new context lands; there is no separate Resolve or Approve pass. - -### Listen - -The opening move for a bare request. One message, one prompt: - -> Tell me about the case you want to build. What kicks it off, what stages does it move through, and how does it close out? Drop in any docs you have — paths, paste, or attach. - -What the agent does as input arrives: - -- **Reads everything mentioned.** Path, dragged file, named doc → read immediately, in parallel when multiple. "Everything in `~/process-docs/`" → `ls` + parallel Reads. -- **Narrates content, not filenames.** One short line per doc about *what's in it*: `vendor-onboarding.md — 4 stages (Intake → Compliance → Finance → Activation), 2 personas, 8-hour SLA on Compliance.` -- **Partial reads for huge docs.** Past ~2000 lines, read the first chunk, narrate the signal, decide if more is needed. Unreadable formats (`.docx`, `.pptx`, scanned PDFs) → one paste request; PDFs ≤ 10 pages read directly. -- **Mid-flow docs are first-class.** New doc after the sketch exists → re-read, update the model, narrate the delta. -- **Named systems seed grounding.** Deployed resources, apps, connectors, systems named by the user feed the §Tenant grounding light pass. - -Listen asks nothing beyond the opener. Gaps are filled by assumption in Sketch, not by questions. - -#### Domain-vocabulary capture (during Listen) - -Capture verbatim into the model: **roles** (exact casing — `CFO`, `Triage Nurse`), **domain nouns** (`Vendor` vs `Supplier` — never homogenize), **stage labels**, **decision outcomes** (`Approve` / `Decline` / `Needs Info`, not synonyms), **integration shortnames** (`Workday`, never "the HR system"). Provenance `verbatim:""` per [sdd-generation-rules.md § Source ledger](sdd-generation-rules.md#source-ledger-provenance). Synonym drift is a fidelity defect ([§ Domain fidelity](sdd-generation-rules.md#domain-fidelity)). - -#### File / attachment / document detection (during Listen) - -When the user mentions `file`, `attachment`, `PDF`, `upload`, `evidence`, `receipt` (as artifact, not domain noun), pick the best-matching pattern from the indicators and record the decision — ask only if the user's own words point at two patterns at once: - -| Pattern | Indicator phrases | SDD shape | -|---|---|---| -| Caller pre-uploads at case start | "caller submits a PDF", "uploaded with the request" | `Category: In`, `Type: file` — Use Case 9; caller obligation surfaces in the confirmation. | -| Connector downloads mid-case | "fetch the attachment from email", "pull from Drive / S3" | `Category: Variable`, `Type: file` from a task Outputs `->` row — Use Case 10. | -| Stores URL/metadata, not bytes | "we just store the link", "we keep the document ID" | `Type: string` (URL) or `Type: jsonSchema` (metadata). NOT `file`. | - -### Sketch — best assumption, every field - -Fill the complete SDD shape against [`sdd-template.md`](../assets/templates/sdd-template.md) from what Listen captured, deciding every open field by best assumption. Authority order per [sdd-generation-rules.md § Content authority hierarchy](sdd-generation-rules.md#content-authority-hierarchy) — platform schema and compliance constraints override user phrasing (apply the override silently; it becomes a decision line). Every non-verbatim value gets a source-ledger entry AND a line in the confirmation's `Decisions` block. Every stage, task, and configured SLA also gets a durable `Design Rationale` in the model explaining the kind/type, activation/sequencing, and routing/threshold choice; the confirmation summarizes it but does not replace it. The model lives in memory — **no draft file, no checkpoint writes**; `sdd.md` is written later at build start. - -**Assumption playbook** (former ask-list, now decided and disclosed): - -| Field | Best assumption | -|---|---| -| Trigger type | External system / portal / form / inbound event / record-created mentioned → **Connector Event** with that source (unprovisioned tenant object stays an event trigger — never downgrade to Manual); schedule/recurring → **Timer**; otherwise → **Manual**. | -| Task type on ambiguous verbs (`review`, `approve`, `validate`, `decide`, …) | Named human role or judgment implied → `action`; framed as automated/AI → `agent`; truly even → `action` (keeps a human in the loop; the user can flip it in one correction). Compliance trigger phrase (HIPAA, ECOA, FINRA, "licensed X", …) → `action`, always ([§ Task-type override priority](sdd-generation-rules.md#task-type-override-priority)). | -| "Manual" in-case work | Starts a new case → Manual trigger; optional worker-launched task → `adhoc` + `Required: No`; worker-chosen exception/rework lane → secondary stage with `user-selected-stage`. Pick by context; disclose. | -| Case exit | Last primary stage completes (`required-stages-completed`, `Marks Case Complete: Yes`) unless the user described another close-out; alternate outcomes → non-completing case-exit rules. | -| Stage exit ↔ Marks Complete pairing | Derive mechanically per sdd-template Key Rule 4 — never author an illegal pair. | -| SLA | Only when the user mentioned timing; take their words literally ("about a day" → 1 day). No timing mentioned → `—`. For every SLA, decide scope, status, and response separately (§ SLA response model). No stated response → `notify-only` for both statuses; never invent a stage or task for a notification. | -| Case name / prefix | PascalCase from the domain noun; prefix = 2–4 letter mechanical derivation. | -| Personas | Named roles verbatim; none mentioned → single `Process Owner`. | -| Optional fields untouched by the user | `—`. Never a question. | -| Resources / connections | §Tenant grounding light pass: single confident match adopted, everything else `resolve at build`. | - -**Structure rules while sketching:** §1.5 declare-vs-xref — mint a §1.5 row ONLY for `In`/`Out` args, trigger-payload Variables, and state read by a condition or ≥ 2 consumers; a single upstream output feeding one consumer is referenced directly (`<- "Stage"."Task".out` / `vars.$xref(...)`), never relayed. Required fields (case name, prefix, ≥1 trigger, ≥1 stage, ≥1 task per stage with type, ≥1 case exit) must all be settled — by user input or by playbook assumption. - -**Other-path sweep — mandatory before confirmation.** Do not design only the primary flow and wait for the user to ask about alternatives later. Check the source for: rework / needs-info loops; rejection, withdrawal, and cancellation; SLA escalation; external-system failure; manual override or worker-selected side work; optional side work; and terminal outcomes that differ from successful completion. For each scenario, choose the correct model: interrupting secondary stage, terminal case-exit, non-completing case-exit, task-level branch, `adhoc` task, SLA notification only, or "not modeled" when the source explicitly rules it out. If the source names or strongly implies a scenario, model it by best assumption and disclose it in **Other Paths Considered**. If the source has no signal at all, spend the one clarifying call on a single bounded question before confirmation: "I don't see any other paths beyond the primary flow. Should I add standard paths for rework, cancellation/withdrawal, SLA escalation, or keep only the primary flow?" - -**Buildability musts** — settle all nine by assumption and surface each in the confirmation; they are where designs silently become unbuildable: (1) other-path trigger source (gate decision → `selected-stage-completed/-exited` + IF; person → `user-selected-stage`; external/global event → one `wait-for-connector` entry on the secondary stage; SLA at-risk/breach that requires case work → one `sla-status-change` entry whose target and SLA title — plus an at-risk escalation title for an at-risk row only — are declared in the SDD, while warning-only escalation stays a notification; interrupting flags on stage + entry rows; terminal `exit-only` vs `return-to-origin`; never duplicate global-event exits/tasks across primary stages); (2) every decision outcome routes somewhere — no dead-end status values, and an outcome that targets a lane keys that lane's entry; (3) every configure/decide task's output lands in a variable or direct reference; (4) every send/connector/agent's required inputs map to variables/literals/upstream outputs as far as knowable without schemas — the rest resolves at build; (5) conditional roles/steps become guarded rules + personas, not prose; (6) a critical-path connector failure gets a modeled other path when the user described failure handling — otherwise note it as an architect advisory; (7) manual-surface classification per the playbook; (8) intended resource names concrete, identities per the light pass; (9) every stage/task/SLA has durable rationale in the model, including why an ordered run is sequential or independent work is parallel. - -**The one clarifying call (rare).** Ask before the confirmation ONLY when: (a) no case is inferable at all (empty or contentless request), (b) the user's own inputs contradict each other on a shape-changing field, (c) the user asked to be asked, or (d) the mandatory other-path sweep found no source signal at all. Batch everything into ONE AskUserQuestion call (≤ 4 questions). An unclear answer → take the best assumption, disclose it, move on — never re-press. Everything else: assume and inform. - -**Red flags — you're about to over-ask.** "I should confirm the trigger type" / "review could be action or agent, better ask" / "the SLA wording is vague" / "this resource has two matches" — STOP: the playbook decides all of these; the decision line in the confirmation is the user's chance to correct. The bar for a question is *contradiction or emptiness*, not uncertainty. Equally, there is NO size gate, no "approval before creating files", no lightweight mode — the only stops in Phase 0 are the one clarifying call (when earned), the confirmation itself, and the explicit-sign-off path. - -### Confirm — the single checkpoint - -One structured **Case Review**, one question. Run the [sdd-generation-rules.md § Finalization](sdd-generation-rules.md#finalization) checks against the in-memory model FIRST — fix failures silently (they are the agent's defects, not the user's decisions); anything unfixable becomes a flagged line. This is the user approval surface and must be complete enough to review without opening `sdd.md`. It is not a generic build plan and not the full SDD prose: it mirrors the SDD sections in scan-friendly tables and grouped bullets. - -**Coverage map:** SDD Section 1 (case definition) → Case snapshot + Data contract + Rules / tiers; SDD Section 2 (stages/tasks) → Stages list + Stage/task detail cards + Other Paths Considered; SDD Section 3 (personas/views) → Case snapshot + stage/task cards; SDD Section 4 (integrations) → Resources & integrations. Anything with a High review item in the SDD model also appears in Review flags. - -Use this exact section order: - -1. **Case snapshot** — table `Item | Review value`. Include case name/prefix, objective, trigger(s), primary personas, completion/terminal outcomes, SLA summary, and build-review preference if already implied. If a value was assumed, mark it with `(assumed)`. -2. **Data contract** — table `Kind | Name | Type | Source | Used for`. Include every user-facing `In` and `Out` argument, every trigger-payload variable, and every state variable that drives routing, SLAs, task inputs, or downstream outputs. Group only purely task-local one-consumer values as `task-local outputs`; do not omit case-level data by saying it appears in `sdd.md`. -3. **Stages list** — table `Kind | # | Stage | Why it exists | Tasks to review | Entry / trigger | Completes / exits | SLA`. Include every primary and secondary stage so the user can see the main path and exception lanes in one scan. List primary stages first in flow order (`Kind: primary`, numbered), then secondary stages (`Kind: secondary`, `# = —`). For secondary rows, `Entry / trigger` names the interrupting signal or decision route, and `Completes / exits` says `return-to-origin`, `exit-only`, or case-close behavior. The `Tasks to review` cell lists every task in that stage as `mode: Task Name (type, persona/resource, required/optional)`, preserving sequence and fan-in: `sequential: Verify identity → Set supplier record`; `parallel: Risk review + Tax validation`; `fan-in: Onboarding decision after both`. -4. **Stage/task detail cards** — grouped bullets, one review card per stage. Each card shows: stage kind and why it is primary or secondary, entry trigger/condition, task type choices with classification rationale, activation rationale, key inputs/outputs, and any resource identity (`resolved`, concrete intended name, or `resolve at build`). For every task, name why its type fits the work (`action`, `agent`, `process`, `api-workflow`, etc.) and why its activation mode fits the timing (`sequential`, `parallel`, `event-driven`, `adhoc`, `fan-in`, `conditional-gate`). Keep it scannable, but every stage must have a card and every task must be named at least once across Stages list or the card. -5. **Other Paths Considered** — table `Scenario | Trigger / condition | Modeled as | Return / close behavior | Review note`. Include modeled exception/secondary paths and any intentionally unmodeled standard path when the user explicitly chose primary-flow-only. User-facing heading is exactly **Other Paths Considered**; do not use any alternate heading. -6. **Rules / tiers** — table `Rule | Where it applies | Data used | Outcome`. Include every conditional gate, amount/risk tier, SLA escalation rule, withdrawal/cancellation rule, rejection/needs-info route, and terminal outcome rule. -7. **Resources & integrations** — table `Family | Intended resource/system | Used by | Resolution`. Include action apps, agents, RPA/processes, API workflows, case-management children, connectors, and named external systems. `resolve at build` is acceptable; a missing row is not. -8. **Decisions I made** — grouped bullets for every assumption, override, resource decision, task-type decision, activation/sequence decision, and intentionally omitted path. Use plain-language source notes (`you said "then"`; `compliance wording`; `no SLA mentioned`). Flagged items (unfixable Finalization findings, missing connections) appear here with a ⚠ marker. -9. **Review flags** — explicit `None` when empty; otherwise list the exact items the user should inspect before approving. -10. **Caller obligation** — mandatory fixed text when any §1.5 row is `Category: In` + `Type: file` (JobAttachment pre-create contract; Studio Web's "Start case" dialog handles it automatically). Omit otherwise. - -**Activation mode vocabulary.** Use these user-visible labels consistently in the review: `sequential`, `parallel`, `event-driven`, `adhoc`, `fan-in`, `conditional-gate`. Use `event-driven` in chat even when the SDD field is `event-triggered`. - -**Completeness gate.** The confirmation is incomplete unless it contains Case snapshot, Data contract, Stages list, Stage/task detail cards, Other Paths Considered, Rules / tiers, Resources & integrations, Decisions I made, Review flags, and Caller obligation when relevant. Do not ask `Build it...`, `Save...`, or any approval question until every section has been shown, even when a section says `None` or `Not used`. Do not replace this confirmation with a generic list of build steps, artifact names, output folder, validation commands, resource-placeholder caveats, or a summary that points to `sdd.md` for the missing detail. - -Confirmation question (AskUserQuestion): `Build it — straight through` / `Build it — pause at the build preview` / `Change something`. The build choice records the Rule 11 preference — never re-asked mid-build. When ⚠ flagged items exist, relabel the first option `Build despite N flagged items — straight through`. For a **design-only** request swap the build options for `Save the design`; for a **draft** request, `Save as draft`. If the user's initial prompt already says to get/save a draft and stop, treat that as the `Save as draft` answer after the Case Review: write `sdd.draft.md` immediately and stop. The draft still uses SDD section/stage/task headings so a reviewer can inspect it directly. - -Corrections (`Change something` or any free text) update the model, re-run affected Finalization checks, and re-show ONLY the changed Case Review sections or rows: changed stage/task cards, data rows, rules, resources, other paths, review flags, and decision lines. A correction never restarts the walk. After showing the changed sections, include a short `Suggested next steps` line before the next confirmation prompt, e.g. `Suggested next steps: approve the updated design, choose preview pause if you want a visual checkpoint, or change another part of the case.` - -**Explicit sign-off requests** ("only after I approve", "I'll review before you build") suppress nothing about the flow but add one explicit approval prompt after the confirmation is accepted and before any file is created — honor it exactly. - -### Template conformance gate — before `sdd.md` is written - -The exact rendered text for `sdd.md` must pass this gate before Write. This is a render check, not a second design review: run it against the in-memory text you are about to write; if the harness makes that impossible, do one shallow post-write structural Read before Phase 1. Do not use the read to redesign the case. - -Required shape: - -- First heading: `# SDD — {Case Name}`. -- `## Table of Contents`. -- Exact section headings: `## Section 1: Case Definition`, `## Section 2: Stages & Tasks`, `## Section 3: Personas & App Views`, `## Section 4: Integrations`. -- Section 1 contains `### Case Metadata`, `### Case Triggers`, `### Case Exit Conditions`, and `### Case Variables`. -- Every modeled primary stage has `### Stage {N}: {Stage Name}`; every modeled secondary stage has `### Secondary Stage: {Stage Name}`. -- Every stage block contains `**Type:**`, `**Design Rationale:**`, `#### Stage Entry Conditions`, `#### Stage Exit Conditions`, and `#### Tasks`. -- Every modeled primary-stage task has `##### Task {N}.{M}: {Task Name}`; every modeled secondary-stage task has numeric secondary numbering `##### Task S{K}.{M}: {Task Name}` where `K` is the secondary-stage order. Do not preserve letter prefixes such as `R.1`, `W.1`, `CC.1`, or `ESC.1`. Each task block contains `**Type:**`, `**Activation Mode:**`, `**Design Rationale:**`, `**Entry Condition:**`, exact marker `**Task envelope**` (no colon), and the matching type-specific detail block. -- Section 3 contains `### Personas` and `### Process App Views`. -- Section 4 contains the integration/resource family headings needed by the modeled task types, or an explicit `> None.` for empty families. - -Forbidden summary-only replacement sections at top level: `## Source`, `## Case Objective`, `## Actors And Systems`, `## Case Trigger`, `## Stages`, `## Business Rules`, `## Task Plan`, `## Resource Resolution`, `## Acceptance Scenarios`. Their presence as the main document structure means the SDD is a summary, not a template render. Also forbid source/build-mode/path narration such as `Source: /...`, `Build mode`, `output folder`, validation-command checklists, or "generated from requirements file" prose in the SDD body. - -If the gate fails, rewrite from the model and template before Phase 1. Do not proceed to planning on a summary SDD, even if a later `caseplan.json` would validate. - -### Build start — SDD written alongside the build - -On a Build answer: - -1. **Transition line** (§What to say while working): `Starting the build — the design doc will be saved alongside as a reference. Say stop anytime.` -2. **Render gate first:** compose the full SDD text from `assets/templates/sdd-template.md` and pass §Template conformance gate. This is the only allowed pre-write SDD check. -3. **One parallel batch:** Write `sdd.md` (full render from the confirmed in-memory model — direct Write, no draft, no rename) + `uip solution init ` (derived exactly as Phase 2 Step 6.0 does; its idempotent skip then applies) + Phase 1's Rule 3 `uip login status` → `registry pull` chain **only if Phase 0's pull did not already succeed this session** — a same-session successful pull is reused, never repeated (SKILL.md Rule 3 fast path). The SDD write is NEVER a standalone blocking turn — it always shares the batch with build actions. -4. **One artifact line** after the write lands: `Design doc saved to ./sdd.md — reference it anytime.` -5. Proceed into [planning.md](planning.md) Step 1 **from the in-memory model** — do not re-read the just-written `sdd.md` in this session except for the shallow template-conformance check described above. Re-read it only when working memory may be stale (context compaction, resumed session); then the file is authoritative (Rule 2). For later sessions and re-runs, `sdd.md` is the contract exactly as if the user wrote it. -6. If `sdd.md` appeared at the path since Phase 0 started, abort instead of overwriting. - -**Design-only request:** write `sdd.md`, report the path in one line, stop before Phase 1. **Draft request:** write `sdd.draft.md`, report, stop — never promote. **Free-text corrections stay first-class after the build starts:** treat one as a targeted edit to the affected artifact (model + `sdd.md` + downstream), narrate it in one line, continue. - -**No-build design + plan request:** when the prompt explicitly asks for `sdd.md` plus `tasks/tasks.md` and says to stop before creating `caseplan.json`, do not enter full Phase 1 and do not read `planning.md` or plugin planning references. If the same prompt already says to produce those artifacts and stop, treat it as the save instruction: show the Case Review, then write the full `sdd.md`, create `tasks/`, write compact `tasks/tasks.md`, and stop in the same response without asking for another approval. If the user only asked to review the plan first, wait for approval before writing. The compact plan is a review handoff for a later build run, so it omits registry-derived files and tenant evidence. - -For this no-build path, prefer progress over exhaustive internal auditing: once the case model covers the stated stages, tasks, global interrupts, SLAs, variables, resources, and rationales, write the artifacts. Do not run the full Finalization checklist, do not inspect schema/planning references, and do not spend a separate turn refining optional SDD prose. The artifact contract below plus the template conformance shape are the gate. - -Compact `tasks/tasks.md` contract for this no-build path: - -- Use T-numbered entries for the case root, triggers, variables/arguments, stages, tasks, entry/exit/condition rules, and SLA/escalation rules that matter to the design. -- Use machine-scannable task headings in the plan: `## T{N}: task "{Task Name}"`. Do not hide task T-entries under dotted subheadings such as `### T12.1`; nested prose is allowed under the H2, but the task entry itself uses a plain integer T-number and quotes the task name. -- Stage entries include `stage-kind`, `entry-rule`, `exit-rule`, `interrupting`, `required`, `sla`, and `rationale`. -- Task entries include `stage`, `type`, `activation-mode`, `entry-rule`, `lane`, `required`, `run-only-once`, `resource-intent`, `identity: resolve at build`, and `rationale`. -- Sequential runs use consecutive single-task lane numbers; every task in the run has `activation-mode: sequential` and `entry-rule: runs-sequentially`. -- Global event/exception entries name exactly one interrupting secondary stage and the rule type (`wait-for-connector` or `sla-status-change`); do not duplicate those events across every primary stage. A `sla-status-change` entry names target + SLA title, plus an at-risk escalation title only for an at-risk row (a breach names the SLA alone) — all declared in the SDD. -- Do not add `taskTypeId`, `activityTypeId`, `connectionId`, resolved schemas, `inputs`, `outputs`, `registry-resolved.json`, or `recipients-resolved.json`. -- End the response with suggested next steps: review the SDD/plan, then run a later build to resolve tenant resources and create `caseplan.json`. - -## HTML preview - -Optional, **on-request only** — never offered proactively. Available any time after the confirmation exists, including mid-build. Self-contained local HTML: Case Definition, collapsible Stages & Tasks with detail panels, Personas & App Views, Integrations; persona/type filters, unresolved-only and schema-view toggles, search, print stylesheet. - -Generation: Read [`assets/templates/sdd-viewer.html`](../assets/templates/sdd-viewer.html), replace the `__SDD_DATA__` token in its `