# PDD-driven Lane Guide When the planner detects a Solution Design Document (SDD) at entry, it runs Lane A — read the SDD, derive tasks, hand off to specialists. This guide covers Lane A end-to-end. > Lane A is reached from the entry guard when the input file contains the marker heading `## Planner Handoff` or the `` marker (the load-bearing detection contract written by Phase D, or present in a hand-written SDD — either signal alone is sufficient). See SKILL.md for the entry guard logic. ## Step 1 — Read the SDD's Planner Handoff header The header appears near the top of every SDD — immediately after `## Document History` in per-project SDDs, or as section 2 (right after Solution Overview) in a solution-overview SDD. **Status gate — check before everything else.** `Status: draft` marks an unfinished Phase D run: sections or the completeness check are missing, or an architecture-blocking SME item is open. Do NOT derive tasks from it. Tell the user the SDD is an unfinished draft and offer: **resume Phase D** (finish the remaining sections, resolve blocking SME items, run the superset check, flip Status to ready) or **regenerate from the PDD**. A missing Status field (hand-written or legacy SDD) → treat as `ready` for backward compatibility and note it in the Step 8 summary. Only `ready` (explicit or legacy-implied) proceeds. **Open SME items travel as assumptions.** A `ready` SDD may carry `## Action Required — SME Review Items` with default-carried rows — that is a normal enterprise SDD, not a defect. Do not refuse it and do not spawn tasks for the items. When deriving tasks (Step 6), append one line to each task whose SDD section is named by an item: `Assumption pending SME confirmation: — proceeding with default `. List the open items in the closing summary so production sign-off stays visible. A `Blocking = yes` row in a `ready` SDD contradicts its Status — treat the SDD as `draft` (gate above). Read these fields: | Field | What the planner does with it | |---|---| | **Status** | `draft` → refuse task derivation (gate above). `ready` → proceed. | | **Solution root SDD / Solution ID / Project SDD role** | Solution scope only. `child` → resolve the root and run the Step 3 root algorithm; `root` → this file's Project Inventory + SDD Index are canonical. `Solution ID` must match across root and children. | | **Execution autonomy** | `interactive` → enter plan mode for task review before execution. `autonomous` → emit live tasks directly. | | **Delivery model** | `cloud` / `automation-suite ` / `standalone` / `unspecified`. Propagated as a platform-constraint line into every specialist task prompt (Step 6). | | **SDD scope** | `single-product` → one SDD file owns one task list. `solution` → one solution-overview SDD plus one per-project SDD; tasks span all projects. | | **Project list section** | Tells the planner where to find the unified project list (e.g., `§10` for RPA, `§3 + §7` for Flow, `Project Inventory` for solution overview). | | **Tasks file** | Where to write `-tasks.md`. Phase D proposes a path; Lane A respects it. | | **Build handoff** | Case SDDs carry this prose row INSTEAD of `Tasks file` — the case build writes `caseplan.json` directly and has no tasks file. Informational only; Lane A parses it for provenance and never resolves it to a path. | | **Generated by** | `uipath-planner`. Used in the summary output to tell the user the SDD's provenance. | | **Generation date** | `YYYY-MM-DD`. Shown to the user in the summary. | **Missing or malformed fields:** default `Execution autonomy` to `interactive` (safer), default `Delivery model` to `unspecified` (no constraint propagated — pre-existing SDDs lack the field), default `SDD scope` to `single-product`, infer `Project list section` from the template type, default `Tasks file` to `-tasks.md` (EXCEPT when the header carries `Build handoff` — that is a Case SDD, where `Tasks file` is absent by design: default it silently and do NOT report it as a defaulted field). **Track each defaulted field** in a session-local list — Step 8 surfaces them in the user-facing summary so the human reviewer can correct the SDD before tasks are emitted. Do not silently swallow the defaults. **Autonomy override on resume:** if the user's resume message explicitly requests review or interactive handling, honour the message over the header's `Execution autonomy` value (do not re-ask). ## Step 2 — Check for an existing tasks.md If the file at `Tasks file` already exists (resume scenario), ask the user via `AskUserQuestion`: > A task list already exists at ``. How should I proceed? > > 1. **Continue with the current task list** *(recommended)* — pick up where you left off; checkbox state preserved > 2. **Regenerate from the SDD** — discard the current task list and rebuild from the SDD; checkbox state lost (or preserved per identity matching, see [plan-and-tasks-format.md → Regenerate logic](plan-and-tasks-format.md#regenerate-logic-pdd-driven-lane-only)) - **Choice 1:** read the existing tasks.md → recreate live `TaskCreate` calls with status preserved → no SDD re-parsing needed → done. - **Choice 2:** parse the SDD fresh, run identity-matching against the old file (preserve completed work), write the new tasks.md, emit live tasks. See [plan-and-tasks-format.md](plan-and-tasks-format.md) for the regenerate algorithm and archive-footer format. If the file does not exist (first run), proceed to Step 3. ## Step 3 — Parse the SDD project list **Solution scope → run the root algorithm.** When the handoff says `SDD scope: solution`, never derive tasks from a single file — a child alone yields a partial task list; the root alone lacks implementation detail. Deterministic algorithm: 1. **Resolve the Solution root.** `Project SDD role: child` → open the `Solution root SDD` path (fallbacks: `*-solution-sdd.md` beside the file, else ask the user). `Project SDD role: root` (or the file IS the overview) → it is the root. 2. **Read the root's Project Inventory and Per-Project SDD Index** — the canonical project list. 3. **Verify every indexed child**: the file exists, carries the same `Solution ID`, and is `Status: ready`. Any child missing, ID-mismatched, or still `draft` → STOP and ask via `AskUserQuestion`: finish/regenerate the child first *(recommended)*, or derive a partial task list with the exclusions named explicitly in the plan header. 4. **Read every child SDD's detailed architecture** (its `Project list section` — nodes, workflows, tools, pages, schemas, integrated components). The overview alone is never enough to derive implementation-level tasks. 5. **Merge shared resources and cross-project dependencies** from the root's Shared Assets & Queues and Cross-Project Data Flow sections — each shared queue/asset/connection is created ONCE (one task, at solution level), and dependency edges follow build-before-consume ordering. 6. **Write exactly ONE canonical tasks file** — the root's `Tasks file` value. Never write a per-project tasks file in solution scope; the end-to-end testing and packaging tasks come last, after every component's build + testing tasks. For single-product scope: read the section named in the `Project list section` header field. The project list is the canonical source for tasks — every project becomes a subset of tasks routed to the appropriate specialist. Common section locations per template: | Template | Project list location | |---|---| | RPA single project | §11 Project Structure (workflow inventory) | | RPA Master Project | §10 Master Project Architecture (sub-project list) + §11 Workflow Inventory per sub-project | | Flow | §3 Nodes Inventory + §7 Integrated Components | | BPMN | §4 Activities Inventory + §9 Integrated Components | | Case | §2: Stages & Tasks + §4: Integrations | | Agent | §9 Project Structure + §3 Tools | | Coded App | §10 Project Structure + §9 Integrated Components | | API Workflow | §10 Project Structure + §5 Connectors | | Solution overview | Project Inventory section + Cross-Project Data Flow section | For Case Management, the case itself is the project. Read Section 2 for the stage/task implementation surface and Section 4 for external component dependencies; do not expect a legacy `Project Structure`, `Tasks Grid`, or `Task Type Registry` table. Extract per project: - Project name (used for the `Identity` tuple) - Product (RPA / Flow / BPMN / Case / Agent / Coded App / API Workflow / IXP / Function) - Sub-type (for RPA: Process / Library / Test Automation) - Role (Dispatcher / Performer / Reporting / Library / Test / etc.) - Framework (Sequence / REFramework, for RPA) - Input / Output queues (for Master Project sub-projects) - Workflows / nodes / tools / pages / steps within the project ## Step 4 — Pick the multi-skill pattern Based on the project list, pick the matching pattern from [multi-skill-patterns-guide.md](multi-skill-patterns-guide.md): | SDD shape | Pattern | |---|---| | Single RPA project, no deploy hint in §16 | Pattern 1 (simplified — drop deploy steps) | | Single RPA project, §16 specifies Orchestrator deploy | Pattern 1 | | RPA Master Project | Pattern 1 per sub-project, integrated via shared queues; cross-project deploy via `uipath-solution` (single `.uipx`) | | Flow with §7 Integrated Components that reference unbuilt resources | Pattern 2 | | Flow whose §7 integrated components are pre-existing | Pattern 3 | | BPMN with §9 Integrated Components that reference unbuilt resources | Pattern 2 (substitute `uipath-maestro-bpmn` for `uipath-maestro-flow`) | | BPMN whose §9 integrated components are pre-existing | Pattern 3 (substitute `uipath-maestro-bpmn`) | | Case Management with §4 integrations that reference unbuilt resources | Build external components first, then `uipath-maestro-case`; inline `action`, connector, timer, and child-case task details stay with the Case specialist | | Case Management whose §4 integrations are pre-existing or unresolved portable intent | `uipath-maestro-case` build task first; unresolved IDs/folders travel as review items for the Case specialist's registry discovery | | Any SDD with a filled "IXP / Document Understanding Models" table | Add an IXP model build + validation task via `uipath-ixp` per model, ordered before its consumer's build tasks | | Any SDD with a filled "Coded Functions" table | Add a Function build + validation task per function via `uipath-functions`, ordered before its consumer's build tasks | | Agent with RPA tools in §3 Tools | Pattern 5 | | Coded App | Coded App build + `uipath-solution` deploy + testing (when wrapped in `.uipx`); otherwise `uipath-coded-apps` self-deploys | | API Workflow | API Workflow build + `uipath-solution` publish + testing | | Solution scope | Compose patterns per project, sequenced by cross-product integration order (dependencies before dependents) | > **Deploy routing is constraint-gated.** Before emitting any deploy task, check the handoff header's `Delivery model` against [platform-availability-guide.md](platform-availability-guide.md). When Solutions (`.uipx`) is blocked for that model — standalone, Automation Suite older than 2.2510, or a user exclusion — replace every `uipath-solution` deploy/publish step in the table above with per-package Orchestrator publish routed to `uipath-platform`. An SDD whose §18 the Constraint Gate rewrote already says this; apply the same rule when entering Lane A with a hand-written SDD whose §18 does not. ## Step 5 — UI element targeting (only when §9 contains UI applications) If the SDD's §9 Application Inventory contains web / desktop / Citrix applications AND the plan loads `uipath-rpa` for a workflow that interacts with them, ask the UI batch as a single `AskUserQuestion` call (3 questions, batched): > *Question 1 — App type:* What kind of application are we automating? > 1. Web / browser app > 2. Desktop app > 3. Citrix / remote session > > *Question 2 — Targeting approach:* How should I handle the UI elements? > 1. **I build it, you review it** *(recommended)* > 2. **You indicate each element** in Studio's Selector editor > > *Question 3 — App state:* Is the app open on your machine? > 1. **Yes, it's open and ready** > 2. **No, I'll open it first** — tell me when ready > 3. **Skip discovery for now** — scaffold with placeholder selectors Question phrasing rules (govern every user-facing question in any lane): 1. **No internal jargon** (snapshot, hand-wire, AutomationId, selector candidate, autonomous capture, target configuration) — plain developer language only. 2. **No domain or app names in question text** ("What kind of application", not "What kind of HR application") — domain lives in the plan header. 3. **Never invent a third option for Q2** — the two canonical targeting options above are the contract. Skip individual questions per the rules: - **Skip Q1** if §9 names the app kind explicitly (web / desktop / Citrix in the Interface column). - **Skip Q2** only if the user explicitly asked for one targeting approach. - **Skip Q3** if the user already stated the app is running, not yet open, or asked to skip discovery. Skip the entire batch if the plan does not include UI automation (pure data-processing, API-only, agent-only, flow-only). **Resumed session:** Q1 resolves from §9 Application Inventory; Q2 (targeting approach) and Q3 (app state) are session-bound and have no SDD field — re-ask them when the current conversation lacks their answers. Record the answers in the tasks.md header for traceability and for the implementation specialists to consume. ## Step 6 — Derive tasks Walk the project list. For each project, emit task rows per the matched pattern. Use the schema in [plan-and-tasks-format.md](plan-and-tasks-format.md). Key rules: 1. **One task per discrete deliverable.** A workflow file → one task. An Orchestrator queue → one task. An asset → one task. 2. **Identity tuple is stable.** `::`. Use kebab-case or PascalCase consistent with the SDD's naming. 3. **Skill prompt references SDD sections explicitly.** "Implement `Process/CalculateTotal.xaml` per §11 row #3 of ``. Use exact data field names from §5." 4. **Anti-hallucination rule appended verbatim** to every Skill prompt. 5. **Blocked-by edges** capture the dependency order — leaf resources before consumers, build before testing, testing before deploy. 6. **Mandatory testing task per generation skill.** Inserted between generation tasks and any deploy task. 7. **Propagate the delivery model.** When `Delivery model` is `automation-suite` or `standalone`, append one constraint line to every Skill prompt: "Deployment target: — do not introduce products or features unavailable there." Skip the line for `cloud` / `unspecified`. ## Step 7 — Write tasks.md Compose the file using the schema in [plan-and-tasks-format.md](plan-and-tasks-format.md). Header lists Source SDD, SDD scope, Execution autonomy, Generation date. Body is the task list. If regenerating, append the Archive footer for removed tasks. ## Step 8 — Plan-mode review (interactive autonomy only) If `Execution autonomy: interactive`, call `EnterPlanMode` with the full tasks.md content. Wait for user approval. - Approval criteria: any response without specific change requests. "Looks good", "ok", "proceed", "yes", or a topic change all count as approval. - If the user requests specific changes, incorporate them and re-present (max 3 revisions; after that, proceed with the latest). - On approval → `ExitPlanMode` → Step 9. If `Execution autonomy: autonomous`, skip plan mode. Output a summary instead: ``` Generated : tasks. Skills involved: uipath-rpa, uipath-platform, … Starting execution autonomously. ``` **If Step 1 defaulted any handoff fields**, append a "Defaulted handoff fields" line to the summary listing each field and the value used: ``` Defaulted handoff fields: Execution autonomy → interactive, Tasks file → . Review the SDD's `## Planner Handoff` table and re-run if any of these are wrong. ``` In `Execution autonomy: interactive` mode, prepend the same "Defaulted handoff fields" block (when applicable) to the `EnterPlanMode` payload so the reviewer sees it at approval time. ## Step 9 — Emit live tasks Emit `TaskCreate` calls one per task row, respecting the row order. After all tasks are created, emit `TaskUpdate` calls with `addBlockedBy` to set up dependencies. Apply Rule G-8: if any TaskCreate or TaskUpdate fails, log a single warning, continue without live tasks, and do not retry. The tasks.md file is the authoritative deliverable. ## Step 10 — Hand off The planner's job is done. The main agent reads the live tasks (via TaskList) and walks them in dependency order, loading the appropriate specialist for each. As tasks complete, the planner — invoked again by the main agent on TaskUpdate events, or whenever it next runs in this project — refreshes the corresponding checkbox in tasks.md (`[ ]` → `[~]` → `[x]`) so that future sessions see current state. > Implementation note: the planner does not directly observe TaskUpdate events. The "refresh tasks.md from live tasks" responsibility lives in the main agent's session loop, not in this skill. This skill writes the file once and trusts the agent to keep it in sync. On next entry to Lane A, the planner re-reads the file and proceeds. ## Lane A budget | Scenario | `AskUserQuestion` calls | |---|---| | First run, no UI apps in §9 | **0** (plan-mode review uses EnterPlanMode, not AskUserQuestion) | | First run, UI apps in §9 | **1** (Step 5 UI batch, only when at least one of Q1/Q2/Q3 is unresolved) | | Resume run (existing tasks.md) | **1** (continue / regenerate) — plus 0-1 for UI batch if unresolved | | Maximum | **2** under any realistic scenario | This stays well within the 5-call budget defined in the planner's Critical Rules.