PowerSolver 2.0 Wizard User Guide

This guide walks you through every screen of the Planning Wizard with detailed explanations, tips, and troubleshooting.

Overview

The Planning Wizard has an optional AI front door (Step 0) plus 7 authoring steps:

┌──────────────────────────────────────────────────────────────────────────────────┐
│  Step 0    Step 1    Step 2    Step 3    Step 4    Step 5    Step 6    Step 7    │
│  AI        Define    List      Define    Define    Pinned    Solver    Review    │
│  Intake    Problem   Entities  Values    Rules     Assign    Settings  & Solve   │
└──────────────────────────────────────────────────────────────────────────────────┘

Getting Started

Login Screen

After logging in, you'll see the main dashboard.

Main Dashboard

The dashboard shows:

Sidebar Controls

Step 0: AI Intake — the cornerstone of the AI integration

How it works end-to-end

You answer 5 questions
        │
        ▼
Each answer → PowerAI validates it (HITL) → shows you its interpretation → you confirm
        │
        ▼  (all required answers confirmed)
Click "Generate" → PowerAI runs the generation pipeline
        │              (generation_intent → generation_spec → validate → repair)
        ▼
PowerAI returns a §5bis JSON spec
        │
        ▼
Wizard imports it via importProblem() → Steps 1–7 are pre-filled
        │
        ▼
You review / edit any field, then Solve in Step 7

The 5 intake questions

The intake form asks five qualitative questions. Each builds context for the next — PowerAI sees your earlier confirmed answers when interpreting later ones.

Write naturally. Numbers help ("45 nurses", "50 shifts per week") — PowerAI's validators check that the generated spec contains the counts you stated.

Human-in-the-Loop (HITL) validation

This is the part that makes Step 0 trustworthy. You do not answer all five questions then hope. Instead:

1. You answer one question and click Validate.
2. PowerAI reads your answer (plus all previously-confirmed answers as context) and presents its interpretation back to you — a short summary of what it understood.
3. You either confirm (the answer locks, a green check appears, the next question unlocks) or edit and re-validate.
4. Repeat until all required questions are confirmed.

Questions you haven't reached yet are locked (greyed out). Confirmed answers collapse into compact green cards with an edit pencil — click it to reopen and re-validate any earlier answer. By the time you click Generate, PowerAI has already shown you — and you've already approved — its understanding of every input. No surprises in the generated spec.

Choosing the AI provider and model

A provider/model picker sits near the top of Step 0:

• AI Provider dropdown — lists every provider with an API key configured in PowerAI Admin (OpenAI, Anthropic, DeepSeek, Groq).
• Model dropdown — the models available for the selected provider; the configured default is marked (default).

If no provider is configured, the picker shows a warning linking to PowerAI Admin. The header badge shows the active provider/model pair once loaded. You can change provider/model any time before clicking Generate.

Generate

Once all required questions show green checks, the Generate button enables. Clicking it:

1. Sends your confirmed intake context + chosen model to PowerAI's /ai/generate endpoint.
2. PowerAI runs its multi-agent generation pipeline (intent extraction → spec generation → deterministic schema validation → LLM repair if validation fails).
3. A progress bar tracks the pipeline stages live (streamed via Server-Sent Events).
4. On success, the resulting §5bis JSON is imported into the wizard store — Steps 1–7 are now populated.
5. The wizard advances you to Step 1 so you can review.

Long-running generation and recovery

Generation can take 30–90 seconds depending on model and problem complexity. The wizard handles this gracefully:

• The job id is stored in sessionStorage while generation runs.
• If you close the tab or refresh mid-generation, Step 0 detects the pending job on reload and resumes tracking it (or recovers a completed result). Pending jobs older than 30 minutes are discarded.
• If generation fails, Step 0 shows a clear error and you can retry — your confirmed answers are preserved.

What PowerAI generates

PowerAI's 2.0 prompts emit only the §5bis shape: collections with your hosts and entities, a list variable wiring them together, the previous + host built-in shadows, the canonical startTime / endTime derived shadows, and unassigned_count (hard) + minimize_property (soft) constraints.

After import — you are still in control

The generated spec is a starting point, not a final answer. Every field lands in Steps 1–7 as editable wizard state:

• Step 1 — the problem type and sequence-mode toggle PowerAI inferred
• Step 2 — the entities it extracted, with their properties
• Step 3 — the hosts and the §5bis sequence configuration
• Step 4 — the constraints it mapped from your rules description
• Steps 5–6 — pinned assignments and solver config
• Step 7 — the full JSON ready to review and Solve

Walk through each step. Adjust anything PowerAI got wrong. The HITL validation makes big misunderstandings rare, but the entity counts, property values, and constraint weights are all worth a human eye before solving.

Returning to Step 0

When to skip Step 0

Skip straight to Step 1 and author manually when:

• You already have a §5bis JSON file — use the header's Open button to import it directly.
• Your problem is tiny (2–3 entities) — manual entry is faster than describing it.
• You're iterating on a known problem and only changing a few values.
• No AI provider is configured in PowerAI Admin.

Step 1: Define Your Problem

Purpose

Tell PowerSolver what kind of problem you're solving. This step configures the wizard for your specific use case.

Fields

Problem Type Options

Problem Type Info Card

When you select a problem type, an info card appears showing:

• Description of the problem type
• Examples of typical use cases
• Entity label (what you'll call your entities)
• Value label (what you'll call your values)

Buttons

Tips

• Be specific in your problem statement — the AI advisor uses this to give better suggestions
• If unsure which problem type to choose, start with "Generic (Custom)"
• Your problem statement and success criteria are saved but don't affect the solver directly

Common Issues

Understanding "Consecutive on a host"

This is the setting that turns the wizard from a basic assignment tool ("Task A goes to Alice") into a real scheduler ("Task A goes to Alice from 09:00 to 09:30, then Task B from 09:30 to 10:15"). This subsection walks through what actually happens once you flip it on, using a small example you can paste into the wizard.

What you provide, and what PowerSolver fills in

When you turn on "Consecutive on a host", you describe a small handful of facts:

• The people, vehicles, or crews doing the work. For each one, you give the time their day begins (e.g. Alice starts at 09:00).
• The things being done. For each one, you give how long it takes (e.g. Login API takes 30 minutes).

That's it. You never type a start time for any task — only for the people. So how does the schedule know when each task starts?

PowerSolver fills it in. The moment it decides "Login API goes first on Alice's queue", it can compute:

• Login API's start time = Alice's start-of-day = 09:00.
• Login API's end time = its start + its duration = 09:00 + 30 min = 09:30.

And the moment it decides "Mobile shell goes after Login API on Alice's queue", it can compute:

• Mobile shell's start time = whatever the previous task on Alice's queue ended at = 09:30.
• Mobile shell's end time = 09:30 + 45 min = 10:15.

These auto-computed answers — the task's start time, its end time, the person it landed on, the task right before it in the queue — are called shadow variables. You see them on the Solution and Insights pages. You never enter them; they fall out of the placement PowerSolver chose.

The name "shadow" is meant literally: these values follow the schedule around. The instant PowerSolver moves a task from Alice to Bob, every shadow value attached to that task updates by itself — its host changes, its start time changes, the task before it changes — without you having to do anything.

Two kinds you'll see in Step 3

• The bookkeeping ones — which person is this task on?, which task is right before me? — are called built-in shadows. PowerSolver provides them for free as soon as you turn on "Consecutive on a host". You never write them.
• The two with a formula — startTime and endTime — are called derived shadows. They use the formulas you saw above: previous task's end time (or the person's start-of-day if I'm first), and my start + my duration. Click Apply default template in Step 3 once and both are set. For most scheduling problems you never touch them again.

If your problem needs something exotic — cumulative load along a delivery route, a custom time-window penalty — see Shadow Variables in the Concepts Guide. The wizard's UI for editing custom formulas is intentionally minimal in this release.

Worked example — 3 tasks, 2 developers

The inputs below match the shape of powersolver-template/task-assignment/1-variable.problem.json — you can import that file in the wizard to follow along live.

Tasks:

Developers (both start their working day at 09:00 on 1 June 2026):

One feasible placement the solver might pick:

• Alice's queue: Login API → Mobile shell
• Bob's queue: DB Schema

The shadow values that come out of that placement:

Or as a tiny timeline:

              09:00     09:30           10:15
   Alice      │ Login API │ Mobile shell    │
              09:00              10:00
   Bob        │ DB Schema             │

Every value in the last two columns was computed by the derived shadows — you didn't write a scheduler, you wrote two one-line expressions.

Why order matters

If the solver instead picked Alice's queue: Mobile shell → Login API, the shadows would say:

Same makespan on Alice's queue, but Login API (priority 1 = critical) now starts at 09:45 instead of 09:00. That's why PowerSolver's default soft constraint targets a derived shadow called priorityCost (= position × (C − priority)): order is a real degree of freedom and the constraint guides the solver to put the highest-priority work at position 1 on each queue.

When not to use sequence mode

If your entities have no inherent order or duration — e.g. "assign this lesson to a room", with no back-to-back relationship between lessons — leave Sequence Mode off and use a basic variable instead. Sequence mode is for problems where what comes before me matters.

Step 2: What Needs Scheduling? (Entities)

Purpose

Enter the items that need to be assigned or scheduled. These are your planning entities.

Understanding Entities

The Entity Cards Interface

Each entity appears as a card with:

• ID (required) — Unique identifier
• Name (required) — Human-readable description
• Properties — Additional fields based on problem type

Adding Entities

Method 1: Add One at a Time

1. Click "Add Item" button
2. Fill in the card fields
3. Click ✓ to save or ✗ to cancel

Method 2: Import from File

1. Click "Import from File" button
2. Select Excel (.xlsx), CSV, or JSON file
3. Map your columns to PowerSolver fields
4. Review preview and click "Import Items"

Entity Properties

Custom Properties

In addition to standard properties, PowerSolver supports custom properties for domain-specific data.

How Custom Properties Work

1. Detection: Custom properties in your JSON are auto-detected
2. Display: New fields are created for each custom property
3. Editing: Edit custom property values just like standard fields
4. Preservation: Custom properties are saved and exported correctly

Examples by Domain

Card Actions

Pinned Assignments (Preview)

Check the 🔒 Pinned checkbox and select a value in "Pre-Assign To" to lock an assignment. The solver will not change pinned assignments.

Common Issues

Step 3: Who or What Can Do It? (Values)

Purpose

Enter the resources that entities can be assigned to. These are your planning values.

Understanding Values and Variables

PowerSolver supports 1-4 value ranges (planning variables):

Each value range appears as a separate tab or section.

Value Properties

Custom Properties on Values

Values also support custom properties that define their capabilities:

Matching Entity and Value Properties

Custom properties create a matching relationship:

Entity (Workload):                    Value (Server):
├── requiredResourceType: "gpu"  ←→  resourceTypes: ["gpu", "cpu"]
├── cpuRequired: 16              ←→  cpuCores: 32
└── memoryRequired: 64           ←→  memoryGB: 128

Tips

• Ensure value skills cover all entity requirements
• Set realistic capacity values
• For time slots, ensure you have enough to cover all entities

Common Issues

Step 4: What Are Your Rules? (Constraints)

Purpose

Define the rules your solution must follow. These are your constraints.

Constraint Levels

Adding Constraints

1. Click the appropriate tab (Hard/Medium/Soft)
2. Click "Add Constraint"
3. Fill in the constraint form:

Available Constraint Rules

Configuring Constraints with Custom Properties

When using custom properties (defined in Steps 2 and 3), you need to tell the constraint which property names to use:

Skill Constraint with Custom Properties

For the skill rule, expand the constraint card to see additional fields:

Example Configuration

Name: Resource Type Match
Rule: skill
Target Variable: server
Entity Skills Property: requiredResourceType
Value Skills Property: resourceTypes
Weight: 10

This constraint ensures entities with requiredResourceType: "gpu" are only assigned to values where resourceTypes contains "gpu".

Constraint Property Reference

Weight Guidelines

Tips

• Start with hard constraints (must-haves)
• Add unassigned constraint to ensure all entities get assigned
• Use weights to prioritize within the same level
• Test with fewer constraints first, then add more

Common Issues

Step 5: Any Pre-Decisions? (Pinned Assignments)

Purpose

Review and manage pinned assignments — entities that are already assigned and should not be changed by the solver.

When to Use Pinning

How Pinning Works

1. In Step 2: Check the 🔒 Pinned checkbox on an entity card
2. In Step 2: Select the pre-assigned value
3. In Step 5: Review all pinned assignments

The solver will never change a pinned assignment.

Tips

• Only pin what's truly fixed
• Too many pins limit solver flexibility
• Check that pins don't conflict with hard constraints

Common Issues

Step 6: How Long Should We Search? (Solver Settings)

Purpose

Configure how long the solver should run and other optimization settings.

Time Presets

Problem Size Summary

The wizard shows a summary of your problem:

Entities: 20 tasks
Values: 6 developers × 10 timeslots
Constraints: 5 hard, 3 soft
Recommended timeout: 120 seconds

Custom Time Setting

If you select Custom:

1. Use the slider to set timeout (10-600 seconds)
2. Or type a specific value in the input box
3. Maximum: 3600 seconds (1 hour)

Timeout Guidelines

Tips

• Longer timeouts generally produce better solutions
• Diminishing returns after a certain point
• Start with Standard, adjust based on results
• For testing, use Quick to verify setup

Common Issues

Step 7: Review & Validate JSON

Purpose

Final review of your problem configuration. Validate, optionally improve with AI, and solve.

The JSON Editor

The large text area shows your complete problem as JSON. You can:

• Review the configuration
• Make manual edits if needed
• Copy the JSON for external use

Validation

Click "Validate JSON" to check for errors:

Common Validation Errors

AI Improvement Feature

Click "Improve with AI" to get AI-powered suggestions:

1. AI analyzes your problem
2. Shows loading indicator while processing
3. Displays improvement suggestions
4. Shows improved JSON for comparison

Solving from Step 7

After validation succeeds, you can:

1. Click "Done" to close the wizard
2. On the main dashboard, click "Solve" button
3. Or use the API to submit the problem

Solution View

After solving, view your results:

Solution Summary

Score Interpretation

Score: 0hard / -2medium / -450soft
       │        │          │
       │        │          └── Soft penalties (lower is better)
       │        └── Medium violations
       └── Hard violations (must be 0!)

Export Options

§5bis Sequence Configuration

When you flipped Sequence Mode on in Step 1, Step 3 shows a Sequence Configuration card with the host-fact picker, the derived-shadow table, and the Apply default template action. This card replaces the 1.x "Time Grain" configuration and Domain Attributes Registry panels.

Host-fact picker

The dropdown lists every variable in Step 3 with assignment type = list. Whichever you pick becomes the host collection — the items that OWN the ordered sequences. Most problems have exactly one list variable (auto-selected).

Apply default template

One click seeds the canonical §5bis derived-shadow pair on the entity collection:

{"name": "startTime",
 "sources": ["previous.endTime", "host.startTime"],
 "expression": "previous?.endTime ?? host.startTime"}

{"name": "endTime",
 "sources": ["startTime", "this.duration"],
 "expression": "startTime + this.duration"}

That pair computes back-to-back start and end times for every entity. The host needs a startTime property (e.g. 2026-06-01T08:00:00); each entity needs a duration property (ISO-8601 string like PT30M). Apply it once after enabling Sequence Mode — for most scheduling problems no further configuration is needed. What this actually does in practice → see Understanding "Consecutive on a host" in Step 1 for the worked example.

The derived-shadow table

Lists the currently registered derived shadows on the entity collection — name, expression, sources. Editing individual derived shadows in the UI is intentionally minimal in this release; for custom expressions (cumulative load, distance, custom time windows) edit the JSON in Step 7 or POST a §5bis spec directly to /api/solve.

What happened to Time Grain and Domain Attributes?

1.x had a TimeGrainConfig block (grain size, planning window) and a Domain Attributes Registry for typed properties. Both are removed in 2.0:

• Time Grain is replaced by derived shadows. startTime and endTime are real LocalDateTime values computed per entity from the host's start time + the entity's duration. No fixed time-slot grid; no grain-size configuration.
• Domain Attributes Registry was a 1.x typing layer. The 2.0 model uses each derived shadow's sources array as the structured contract — the solver knows which properties matter because the expressions declare them. Custom properties still work (any key in an entity's properties bag) but there is no separate registry UI.

Navigation Tips

Progress Indicator

The step indicator at the top of each modal shows your progress:

[Step 1] ─ [Step 2] ─ [Step 3] ─ [Step 4] ─ [Step 5] ─ [Step 6] ─ [Step 7]
   ●          ●          ○          ○          ○          ○          ○
completed  active    upcoming

Saving Your Work

Your work is saved when you:

• Click "Save" on any step
• Click "Next" to proceed
• The wizard auto-saves periodically

Going Back

You can always go back to previous steps:

• Click "Previous" button
• Click on a completed step in the progress indicator

Keyboard Shortcuts

Troubleshooting

Wizard Won't Open

Lost My Work

AI Features Not Working

Validation Keeps Failing

Quick Reference

Step Summary

Button Reference

Next Steps

• Quick Start Guide — Step-by-step tutorials
• Concepts Guide — Understanding planning concepts
• User Guide — Complete reference

Support

• Click the ? icon in any step for context help
• Use the AI Advisor panel for suggestions
• Email: support@planningpowertools.com