| 1 | --- |
| 2 | description: Cross-route stop/continue governance with a concrete recovery matrix and resume map for Generate PPTX. |
| 3 | --- |
| 4 | |
| 5 | # Failure Recovery Governance |
| 6 | |
| 7 | Global stop/continue rules for all four top-level routes, plus concrete failure handling for Generate PPTX. Section 2 applies across routes; Sections 1 and 3 apply only to Generate PPTX. Owning route and stage documents may add narrower handling, but must not weaken the global rules or duplicate this matrix. |
| 8 | |
| 9 | **Hard rule**: A failed required artifact blocks the next gate. A failed convenience surface falls back to the canonical channel and does not block the active route. |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## 1. Generate PPTX Recovery Matrix |
| 14 | |
| 15 | | Failure point | Blocking | Automatic recovery | User intervention | Resume entry | |
| 16 | |---|---:|---|---|---| |
| 17 | | Confirm UI launch failure | No | Re-check `confirm_ui/result.json` once, then use chat fallback | No | [`generate-pptx`](../generate-pptx.md) Step 4 chat confirmation | |
| 18 | | Confirm UI wait timeout | No, if no final result yet | Re-check `result.json` once; keep server cleanup mandatory | Only if user still wants the page | Step 4 same stage or chat fallback | |
| 19 | | User explicitly switches from Confirm UI to chat during any stage | Yes until the unresolved current stage is confirmed | Follow [`confirm_ui.md`](../../scripts/docs/confirm_ui.md)'s in-run switch, retain persisted confirmed stages, then continue the current and remaining stages in chat; never relaunch UI | Confirm in chat unless explicitly delegated | Step 4 current chat stage | |
| 20 | | Confirm UI Stage 1 completed then unexpectedly interrupted while UI remains selected | Yes until final Stage 2 is written/confirmed | Read existing Stage 1 `result.json`, derive a fresh `recommendations.stage2.json` without changing Stage 1, then `--wait-only` for final confirmation | Usually no | Step 4 final Stage 2 write/wait | |
| 21 | | Missing final confirmation | Yes | None | User must confirm or change the values | Step 4 final confirmation | |
| 22 | | Final confirmed value or a later explicit user override is missing, changed, substituted, or weakened in `design_spec.md` | Yes | Repair from the retained final-confirmation object plus any newer explicit instruction; only a fresh recovery turn with no retained state reads persisted final evidence once | Only when the effective value genuinely cannot be honored | Step 4 Gate 1 — confirmation fidelity | |
| 23 | | `spec_lock.md` changes confirmed identity or omits a required execution anchor/routing decision | Yes | Re-author the affected lock rows from the completed Design Spec and current context; do not enumerate page-local literals | No unless the Design Spec itself is incomplete | Step 4 Gate 2 — lock context fidelity | |
| 24 | | Execution exposes a missing Strategist-owned role/plan detail | Yes for the affected page | Repair affected Design Spec/lock fragments under [`executor-base.md`](../../references/executor-base.md) §2.1 | Only if confirmed intent changes | Step 4 Gate 1/2 → Step 6 current page | |
| 25 | | Execution context is fresh, resumed, restarted, compacted/summary-only, external, or unknown | Yes until rebuilt | Read complete Design Spec, then lock, once; reload triggered inputs and latest completed SVG when mid-deck | No | Step 6 current page | |
| 26 | | Step 3 rejects a legacy or incomplete template contract | Yes | Stop template consumption; create a new current workspace through Create Template from the original PPTX/reference, then return with its exact workspace root | Only when required source evidence or template choices are unavailable | Create Template → Generate PPTX Step 3 | |
| 27 | | Formula rendering provider failure | No until the Step 7 readiness gate | Exhaust the provider chain; if unresolved, mark only the affected formula rows `Needs-Manual` and continue | Supply the exact target PNG or change formula policy | Step 4 / Step 7 image readiness gate | |
| 28 | | AI image generation failure | No | `auto`: follow A → B → Offline Manual. Explicit `api` / `host-native`: retry only that path, then mark the row `Needs-Manual` without switching automated providers | Only when missing files are required before export | Step 5 / Step 7 image readiness gate | |
| 29 | | Web image search/download failure | No | Adjust query/source per image-searcher rules, then mark `Needs-Manual` if unresolved | Only if the resource is required and no acceptable substitute exists | Step 5 | |
| 30 | | Slice sheet missing | Yes for derived slice rows | Wait for parent sheet; run `slice_images.py`; rerun image analysis | Yes when sheet was manual/offline | Step 5 slice handling / Step 7 image readiness gate | |
| 31 | | Residual `Pending` or `Failed` image row before Executor | Yes | Re-run path or mark `Needs-Manual` | Only if file must be supplied manually | Step 5 terminal-state check | |
| 32 | | User replaces/adds images after analysis | No | Re-run `analyze_images.py` before reading image facts | No | Step 4/5/6 image-fact read | |
| 33 | | Live preview fails to start | No | Continue generation; report that preview is unavailable | Only if user requires browser preview | Step 6 or `live-preview` Step 1 | |
| 34 | | Live preview closed by user | No | Continue generation | No | Restart through `live-preview` only if requested | |
| 35 | | Browser annotations submitted during generation | No | Defer application until after Step 7 | User asks to apply annotations | `live-preview` Step 2 | |
| 36 | | `svg_quality_checker.py` error | Yes | Review the complete issue set from one unfiltered run; fix all errors and selected warnings in one consolidated edit pass, then perform one verification rerun. If it still fails, use that complete result as the next batch; never check between individual fixes | No unless required asset is missing | Step 6 Visual Construction | |
| 37 | | `svg_quality_checker.py` warning | No | Continue without mandatory modification or acknowledgement; preserve compatible user syntax, and report material fidelity/quality advice when useful | No | Step 6 advisory warning handling | |
| 38 | | Missing `notes/total.md` while the effective Speaker Notes outcome is enabled | Yes | Generate speaker notes before Step 7 | No | Step 6 Logic Construction | |
| 39 | | Step 7 image readiness missing manual files | Yes | None for manual assets; list required filenames and prompts | Yes | Step 7 image readiness gate | |
| 40 | | `total_md_split.py` failure while speaker notes are enabled | Yes | Fix notes format/path, rerun only Step 7.1 | Usually no | Step 7.1 | |
| 41 | | `finalize_svg.py` failure | Yes | Fix SVG/assets, rerun Step 7.2 | Only if source asset is missing | Step 7.2 | |
| 42 | | `svg_to_pptx.py` failure | Yes | If no current matching passing final SVG quality report exists, obtain the complete blocking issue set from the final checker as needed, fix it, rerun the checker against the updated `svg_output/`, and proceed to Step 7.3 only after it reports `passed`; otherwise fix the conversion issue and rerun Step 7.3 | Only if a required artifact is missing | Step 6 final quality gate or Step 7.3 | |
| 43 | | Export succeeds but user wants direct browser edits re-exported | No | Rerun Step 7.2 and Step 7.3 after applied edits | No | Post-export live-preview handling | |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## 2. Global Stop/Continue Rules |
| 48 | |
| 49 | | Condition | Action | |
| 50 | |---|---| |
| 51 | | Required gate artifact missing | Stop at that gate and name the missing artifact. | |
| 52 | | Optional stage not explicitly requested | Do not run it as recovery. | |
| 53 | | Convenience UI/server failure | Fall back to chat or continue without the surface. | |
| 54 | | Derived artifact stale | Regenerate it from its owning source. | |
| 55 | | Required manual artifact missing | Pause and name the exact required artifacts; resume only after they exist. | |
| 56 | | Validation or export failure | Fix the owning source artifact, then rerun the failed operation and affected downstream operations only. | |
| 57 | | Confirmed execution choice cannot be honored | Keep the confirmed requirement visible. Retry the confirmed provider, mode, voice, effect, or path only as its owning workflow allows; if it remains unavailable, stop, request a new decision, or hand off through the owning workflow's declared manual fallback (e.g. `Needs-Manual` with a user summary). Never omit it or switch to another automated value or path silently. | |
| 58 | |
| 59 | **Missing values**: For a field in an existing artifact, follow only the exact requiredness, inference procedure, or fixed default declared by its owning schema or workflow; an active omission with no such rule stops at the owning boundary. Empty values, inactive conditional fields, whole artifacts, derived artifacts, and file-format attributes keep their own declared semantics—do not extend a fallback by analogy. Owning rules label their fallbacks with two terms used across this repository: a **declared-inference / declared-procedure fallback** states its missing condition and a bounded procedure that needs no new user decision; a **fixed compatibility default** states the exact fallback value, applied with one warning. |
| 60 | |
| 61 | **Forbidden — silent downgrade**: Do not skip a required gate because a downstream command might tolerate the missing file, and do not change a confirmed execution value merely to keep the route moving. Fix, pause, or request a new decision at the owning boundary. |
| 62 | |
| 63 | **Proactive production resolution**: Keep final Stage-2 raw fields as evidence. |
| 64 | Resolve durable outcomes as explicit instruction → final Stage 2 → workflow defaults |
| 65 | `enabled` / `disabled` / `disabled`. Audio raises Notes only when Notes is not |
| 66 | explicitly disabled; an explicit notes-off/audio-on conflict stops at |
| 67 | Generate's one-question dependency gate. Keep raw values unchanged and record |
| 68 | outcomes/provenance only in Design Spec §I, never the lock. |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | ## 3. Generate PPTX Resume Pointers |
| 73 | |
| 74 | Here, **final confirmation evidence** means either the explicit final confirmation in the current chat or `<project>/confirm_ui/result.json` with `status: confirmed` and `stage: final`. Planning artifacts alone do not prove that the user confirmed their values. After that gate, a newer explicit user instruction may update only its effective production outcome and provenance in the durable Design Spec; resume from the owning step without reopening Confirm UI. |
| 75 | |
| 76 | The UI wait resume entries below apply only while UI remains the selected |
| 77 | surface. A newer explicit chat-surface instruction follows `confirm_ui.md`'s |
| 78 | in-run switch and resumes the unresolved stage in chat without relaunching UI. |
| 79 | |
| 80 | | Last good state | Resume from | |
| 81 | |---|---| |
| 82 | | Stage 1 confirmation exists, final Stage 2 is missing or unconfirmed, and UI remains selected | Derive a fresh `recommendations.stage2.json` from confirmed Stage 1 and current inputs without changing Stage 1, then run `confirm_ui/server.py <project> --wait-only` for final confirmation. | |
| 83 | | Final confirmation evidence exists; `design_spec.md` is missing, with or without a surviving `spec_lock.md` | Return to Generate Step 4 and [`strategist.md`](../../references/strategist.md) §6.2; read final evidence once into the fresh context, read [`design_spec_reference.md`](../../templates/design_spec_reference.md), author the complete `design_spec.md` from scratch using that state plus source analysis, and pass Gate 1. Then read [`spec_lock_reference.md`](../../templates/spec_lock_reference.md) and re-author the complete `spec_lock.md` from the audited Design Spec plus current context, replacing any orphan lock. Never reconstruct the Design Spec from an orphan lock or retain orphan-lock choices as authority. | |
| 84 | | Final confirmation evidence exists; `design_spec.md` exists and `spec_lock.md` missing | Return to Generate Step 4; in this fresh recovery context read final evidence once to audit the existing Design Spec, then read [`spec_lock_reference.md`](../../templates/spec_lock_reference.md) and author the complete lock from the audited Design Spec plus current context. | |
| 85 | | Final confirmation evidence and both planning artifacts exist, but Gate 1 fails | In a fresh recovery context read final evidence once, repair `design_spec.md`, then re-author every affected lock row. Do not reopen recommendations or infer a replacement from the current lock. | |
| 86 | | Gate 1 passes but Gate 2 fails | Keep the Design Spec unchanged and re-author only the mismatched lock anchors/routing rows from it plus current context. | |
| 87 | | No final confirmation evidence is available | If `confirm_ui/result.json` proves Stage 1 confirmation, resume at final Stage 2; otherwise restart Step 4 at Stage 1. Do not infer confirmed choices from partial planning artifacts. | |
| 88 | | `design_spec.md` and `spec_lock.md` complete, split mode selected | [`resume-execute`](../stages/resume-execute.md) | |
| 89 | | Images acquired but SVGs not started | [`generate-pptx`](../generate-pptx.md) Step 6 | |
| 90 | | SVGs complete and checker passed; effective Speaker Notes outcome enabled and notes missing | Step 6 Logic Construction | |
| 91 | | SVGs complete; effective Speaker Notes outcome disabled | Run any applicable conditional motion handling, then Step 7.2 and export with `--no-notes` | |
| 92 | | SVGs and enabled notes complete | Step 7.1 | |
| 93 | | Step 7.1 complete, export not complete | Step 7.2 | |
| 94 | | Step 7.2 complete, PPTX not complete | Step 7.3 | |
| 95 | | Browser annotations saved after export | [`live-preview`](../stages/live-preview.md) Step 2 | |
| 96 | |
| 97 | **Default - resume at the owning failed step**: Do not restart the planning session or regenerate prior artifacts unless the owning source has changed. |
| 98 |