Design the Solution (Block 1)¶

Your agent reads the PDD and generates the Solution Design Document: one file, sdd.md, at a fixed name at the seed root. Everything downstream binds to it: the plan derives from it, the build follows it, verify checks against it, and handover brings it to as-built. It has to be good enough that a solution architect could hand it to a developer and walk away.

Traditional UiPath delivery	With a coding agent and UiPath Skills
A solution architect reads the PDD and writes the SDD by hand, then takes it through review meetings. Platform limits and policy surface in review, or only in the build.	The uipath-planner skill writes the SDD from the PDD and the contracts in one session, applying UiPath's design rules as it writes. The architect reviews it rather than writes it, and resolves what it flagged.

Before you run: why the agent asks nothing¶

The planner normally asks its questions before designing: execution mode, delivery model, which components exist, which app type. You will see them when you build your next project.

Here the agent is instructed to ask nothing. That saves time, and every answer is already written down: the mode in the prompt, the tenant from your login, the component inventory in contracts/components.md. An agent works on its own only when the brief already answers its questions. If you know an answer yourself, put it in the prompt.

The prompt¶

Copy it into your coding agent, started in the seed folder:

Prompt — block 1 · Design

# Design

Read:
- `PDD.md` — property claims department manager has described how property claims are handled. 
- `CONFIG.md` - describes environment and settings.
- `contracts/` - some technical specs and description of automation blocks that already exist (use what is deployed instead of designing a replacement for it).

Use the **`uipath-planner`** skill and design the solution from the PDD. Run **autonomous** — do not pause for confirmation. **Design only: write the design to `sdd.md` at the seed's root, beside `PDD.md`, and stop** — with `Tasks file: tasks.md` in its handoff header, which is where `2-plan` writes. No task list, nothing built, nothing deployed — `2-plan` derives the tasks next.

`sdd.md` describes what the solution **is** when it runs. It outlives the build and everything downstream binds to it.

Three things I care about:

- **Take every task's type from the PDD's §5.3 decision-nature column**, not from whatever the tenant happens to hold — and name the step in each task's *Design Rationale* (`PDD step 4.3`), which is how the checker verifies it.
- **Build only what `contracts/components.md` lists** — seven agents and one Action app, no tools, no evaluation sets. How you shape the case — stages, ordering, conditions, SLAs — is yours.
- **Add the two sections in `method/sdd-addendum.md`** after Section 4, headings as written: the claim entity with its write-ownership matrix, and what the design fed back to the PDD.

Then check your own work and fix what it finds:

```bash
python3 1-design/check_sdd.py sdd.md --pdd PDD.md
```

One command, both checks: it runs the planner's shape audit and then checks the design against the process — task types against the PDD, one writer per column, every read variable produced, real argument names, tables that render. Read its rules when a failure is unclear — each one is a shape that built and then failed.

**Done when a solution architect could hand this to a developer and walk away** — every stage, task, rule and human decision described well enough to build from, with nothing left to guess. The checker exiting 0 is the floor, not the finish.

If a check fires on something you believe is right, say so and leave it — a wrong rule in the checker is worth more to us than a file edited to satisfy it.

The prompt stops the agent after the design, and the task list comes in the next block. One document answers one question; a design that also explains the build order becomes two documents describing the same thing, and the copy nobody edits is the one that goes stale.

Steps:

Read PDD.md, CONFIG.md and contracts/ (components, claim entity, review task, provided processes)
Load the uipath-planner skill; run autonomous, design only
Write sdd.md at the seed root, with Tasks file: tasks.md in the handoff header
Add the two sdd-addendum sections (entity write-ownership matrix; design feedback to PDD)
Run the gate: python3 1-design/check_sdd.py sdd.md --pdd PDD.md; fix findings and rerun until clean
Update PROGRESS.md

Review the design¶

The agent finishes in minutes; your review is what catches the defects. Four things to check by hand:

Every step, its nature respected. Walk the PDD's §5.3 table against the design: judgement steps became Agents, rule-expressible steps became expressions or deterministic tasks. Each design task should name the PDD step it implements.
Where two sections state the same fact, do they agree? A long generated document is written section by section, and consistency between distant sections is exactly what a sequential writer is worst at. Find the pairs (a field listed in two tables, an owner named twice) and compare them; that is where design defects live.
Budgets as numbers. Every agent's summed inputs against the platform's cap, stated arithmetically, not as "should fit".
Disagreements resolved out loud. Where a contract and the PDD pull differently, the design follows the contract and says so in its Design Feedback section. A silent resolution is invisible and therefore uncheckable.

The gate¶

python3 1-design/check_sdd.py sdd.md --pdd PDD.md

The planner checks the document's shape itself: sections present, tables well-formed. The script cross-check verifies it against the process: task types match the PDD's decision-nature column, one writer per data column, every variable that is read is produced by something, argument names are real. Run both, trust neither alone.

Remember

Especially on large tasks, agents often report work as done after missing half of it. In this workshop we know what the SDD should contain and can check it with a script; on your next project, it's your eyes. Never jump to the next step assuming agents are perfect. Not just yet.

This gate is also what makes the exercise model-proof: different models design differently, and a weaker one will occasionally, and silently, put arithmetic where judgement belongs. The gate catches that on any model, which is why the answer to design variance is a check downstream, never a thicker requirements document.

Proof¶

What a passing design looks like, from a real run of this block.

The stage model, answering the PDD's §5.5 exactly:

| 2 | **Stage model** | Six primary stages (Intake → Eligibility Screening → Awaiting Inspection →
Analysis → Claim Review → Approved) plus two secondary stages (Denied, Missing Details) | `PDD.md`
§5.5 fixes the eight stages, their owners and which are required for completion; *Approved* is the
healthy ending and *Denied* is explicitly the secondary unhappy ending. |

One task's Design Rationale, naming its PDD step and disclosing a substitution instead of making it silently:

### Case Triggers

**Design Rationale:** `PDD.md` §2.1 says the claim arrives one at a time through Claims Intake, and
§9 lists *Claim filed* as an inbound event correlated by claim reference. No Claims Intake
connector is provisioned on this tenant and claim registration is served by the `Retrieve Property
Claim` automation (`CONFIG.md`, *What already exists*), so the case starts through the platform's
own start API and registers the claim as its first task. SME Review item 1 records the
substitution; replacing this row with an event trigger later changes no stage and no task.

And the gate:

$ python3 1-design/check_sdd.py sdd.md --pdd PDD.md
0 failure(s), 5 warning(s), 0 note(s)

A design the checker passes and an architect could hand over: every stage, task, rule and human decision described well enough to build from, with nothing left to guess.