@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/plans/prompt-fragments.md

@@ -0,0 +1,53 @@
+# Prompt Fragments
+
+This is the **canonical summary doc** for the conditional prompt fragments feature.
+
+Use it for:
+
+- what the feature is
+- the final design stance
+- shipped status and accepted tensions
+
+## What it is
+
+`promptFragments` lets a workflow step declare small conditional prompt additions that are evaluated at render time against session context.
+
+## Final design stance
+
+- fragments are **runtime-only**
+- they do **not** participate in the compiled workflow hash
+- they are **additive only**
+- they are assembled at the existing prompt-rendering seam
+- steps without `promptFragments` behave unchanged
+
+## Why the final design won
+
+The chosen design kept fragment evaluation at render time instead of pushing it into compilation or scattering new context-plumbing across call sites.
+
+That preserved:
+
+- backward compatibility
+- deterministic compiled hashes
+- a single prompt-construction seam
+
+## Shipped status
+
+This feature is effectively **done**.
+
+Delivered work includes:
+
+- workflow/schema support for `promptFragments`
+- render-time fragment assembly
+- `in` operator support for conditions
+- validation rejecting `{{wr.*}}` tokens in fragment text
+- focused tests covering rendering and validation behavior
+
+## Accepted tensions
+
+- fragment provenance is not separately persisted as its own runtime artifact
+- context projection during rendering is accepted as part of the existing prompt-rendering seam
+- there is no heavy lifecycle/integration harness dedicated solely to fragments
+
+## Source history
+
+The earlier design/review/verification docs for this feature have been removed (they were superseded stubs). This file plus the shipped code/tests is the canonical view.

package/docs/plans/ui-ux-workflow-design-candidates.md

@@ -0,0 +1,120 @@
+# UI/UX Workflow Design Candidates
+
+## Problem Understanding
+
+**Core claim**: AI agents fail at UI/UX design not because they lack knowledge but because they skip the process that converts knowledge into good design. They anchor on solutions before understanding users, produce single outputs instead of alternatives, violate UX laws they can accurately recite, and ignore edge cases, accessibility, and content entirely.
+
+**The 6 failure categories:**
+1. **Process failures** — skips empathy, jumps to single solution, happy-path only, no iteration
+2. **UX law violations** — knows Hick/Miller/Jakob/Fitts/Peak-End/Tesler but doesn't apply them
+3. **Content/communication failures** — designs layout, ignores microcopy, no error states, no onboarding
+4. **Accessibility failures** — color contrast, keyboard nav, touch targets, screen readers ignored
+5. **Context blindness** — no design system, platform conventions, brand, user research knowledge
+6. **Inherent limitations** — can't see/render designs, can't test with users
+
+**Core tension**: Agents CAN recite all UX principles. The failure is enforcement and process, not knowledge.
+
+**What makes this hard**: A checklist prompt doesn't work — an agent can "check" each item while still fundamentally designing the wrong thing. The forcing function must be structural: impossible to advance past Problem Framing without user goals explicitly stated and confirmed.
+
+## Philosophy Constraints
+
+- **Make illegal states unrepresentable**: Solution proposals before user framing are an illegal state
+- **Validate at boundaries**: User goals/problem definition is the boundary; validate before design begins
+- **Structured freedom**: Constrain outcomes (user framing required, alternatives required), not cognition steps
+- **Anti-lazy wording**: 'design a UI for X' is insufficient input; workflow must force specificity
+- **YAGNI**: Don't add phases that don't address a real failure mode
+
+## Candidates
+
+### A: Minimal — Problem-First Gate
+
+**Summary**: 3-phase workflow enforcing exactly one invariant: no solution proposals until user goals and constraints are explicitly stated and confirmed (requireConfirmation).
+
+- **Tensions resolved**: premature convergence
+- **Tensions accepted**: UX law violations, edge cases, accessibility all left to agent judgment
+- **Failure mode**: agent states user goals then proposes a single solution anyway
+- **Repo pattern**: similar to bug-investigation hypothesis-first gate
+- **Gains**: minimal ceremony, fast, blocks root cause
+- **Losses**: only addresses 1 of 6 failure categories
+- **Scope**: too narrow
+- **Philosophy**: honors validate-at-boundaries; conflicts with make-illegal-states-unrepresentable
+
+---
+
+### B: Process Enforcement — Adapted Production Readiness Audit (RECOMMENDED for creation)
+
+**Summary**: 6-phase creation workflow with hypothesis-first, neutral context packet, parallel reviewer families per failure category, synthesis loop, and design spec handoff.
+
+**Phase structure:**
+- Phase 0: Problem framing + user goals + constraints (requireConfirmation always)
+- Phase 1: State design hypothesis — what does the agent currently believe is the right direction?
+- Phase 2: Freeze context packet + declare reviewer families based on declared concerns
+- Phase 3: Parallel reviewer bundle (IA reviewer, UX laws reviewer, accessibility reviewer, edge-cases reviewer, content/microcopy reviewer)
+- Phase 4: Synthesis + contradiction loop
+- Phase 5: Design spec handoff with per-dimension findings
+
+**Complexity branching**: Simple (single-screen, minor change) → skip Phase 1-3, go direct. Standard/Complex → full pipeline.
+
+- **Tensions resolved**: all 6 failure categories; forces alternatives at hypothesis stage; evidence-based per-dimension findings
+- **Tensions accepted**: inherent visual limitations; spec not mockup
+- **Failure mode**: reviewer families produce generic UX advice not tied to actual design context
+- **Repo pattern**: directly adapts `production-readiness-audit.json` structure; auditComplexity branching from `adaptive-ticket-creation.json`
+- **Gains**: comprehensive, structured freedom, all failure categories covered
+- **Losses**: heavier than minimal for simple tasks (mitigated by Simple fast path)
+- **Scope**: best-fit for feature-level and screen-level design work
+- **Philosophy**: all principles satisfied
+
+---
+
+### C: Alternatives-First — Double Diamond
+
+**Summary**: Forces divergence (3 fundamentally different design directions with explicit IA sketches) before any convergence, with adversarial challenge before the agent recommends one.
+
+- **Tensions resolved**: single-solution anchoring; forces genuine exploration
+- **Tensions accepted**: UX laws/accessibility not explicitly enforced
+- **Failure mode**: 3 directions are superficially different (same IA, different metaphors)
+- **Repo pattern**: adapts `architecture-scalability-audit.json` dimension-declaration
+- **Gains**: best for exploring solution space; documents tradeoffs
+- **Losses**: lighter on UX law enforcement; accessibility second-class
+- **Scope**: best as a mechanism within B rather than a standalone workflow
+- **Philosophy**: honors structured freedom; YAGNI tension (adds divergence without enforcing quality)
+
+---
+
+### D: UX Audit — Review Against Principles (RECOMMENDED as companion)
+
+**Summary**: Review workflow for existing designs. User provides a design description/spec; agent audits it against explicit UX dimensions with per-dimension verdicts and evidence.
+
+**Dimensions**: information architecture, Hick/Miller/Jakob laws, Fitts + touch targets, Peak-End + emotional journey, accessibility (WCAG checklist), edge cases (empty/error/loading/first-use), content + microcopy.
+
+- **Tensions resolved**: turns agent UX knowledge into structured application; fully evidence-based
+- **Tensions accepted**: doesn't help with design-from-scratch; requires existing design as input
+- **Failure mode**: agent audits what's in the spec but misses implicit design assumptions not stated
+- **Repo pattern**: directly adapts `architecture-scalability-audit.json`
+- **Gains**: actionable per-dimension findings with references; complements B
+- **Losses**: review only, not creation
+- **Scope**: best-fit as standalone for design review; or used after B to audit the output
+- **Philosophy**: all principles satisfied; mirrors architecture-scalability-audit exactly
+
+## Comparison and Recommendation
+
+**Recommendation: Build B and D as two separate workflows that naturally compose.**
+
+B (creation) and D (audit) serve different moments: B for designing from scratch, D for auditing before implementation. Together they cover the full design process. Neither alone is sufficient.
+
+C's divergence mechanism (3 design directions) should be incorporated as a step within B's hypothesis phase, not as a separate workflow.
+
+A is too narrow — prevents the worst failure but leaves 5 of 6 failure categories entirely to agent judgment.
+
+## Self-Critique
+
+**Strongest counter-argument**: B is too heavy for everyday use. Adding a button to a screen shouldn't require 6 phases and reviewer families. Counter: the Simple fast path (auditComplexity branching) addresses this — simple changes skip everything except problem framing and spec.
+
+**Pivot condition**: If agents produce hollow reviewer findings (generic advice not tied to the actual design context), the reviewer-family approach needs replacement with a simpler rubric where the agent self-scores against explicit criteria rather than running independent reviewers.
+
+## Open Questions for Main Agent
+
+1. Should D be a standalone workflow or a phase within B? (Standalone seems cleaner — used at a different moment in the process.)
+2. What's the right output format for B? Markdown design spec? JSON with structured fields? Decision records?
+3. Should B include a visual vocabulary section — letting the agent describe layout in structured prose (grid, card, list, etc.) as a partial substitute for visual mockups?
+4. Is there a third workflow worth building: a **Design System Audit** that checks whether a proposed design is consistent with an existing component library?

package/docs/plans/ui-ux-workflow-discovery.md

@@ -0,0 +1,100 @@
+# UI/UX Design Workflow Discovery
+
+## Context / Ask
+
+Map the specific ways AI agents fail at UI/UX design work and identify which failures are addressable through workflow structure. Goal: inform the design of a WorkRail workflow for UI/UX design.
+
+## Path Recommendation
+
+`full_spectrum` — need both landscape (catalog of AI failure modes with evidence from UX principles) and reframing (which failures a workflow can actually address vs. which are inherent AI limitations).
+
+## Constraints / Anti-goals
+
+- Not building a visual design tool — agents can't render or see designs
+- Not replacing the human designer — augmenting and structuring agent-assisted design
+- Must produce something an agent can actually execute, not just describe
+
+## Landscape Packet
+
+*(populated in Phase 1)*
+
+## Problem Frame Packet
+
+*(populated in Phase 1d)*
+
+## Candidate Directions
+
+*(populated in Phase 3)*
+
+## Challenge Notes
+
+*(populated in Phase 4)*
+
+## Resolution Notes
+
+*(populated in Phase 5)*
+
+## Decision Log
+
+*(populated as decisions are made)*
+
+## Final Summary
+
+*(populated at end)*
+
+## Candidate Directions
+
+See `docs/plans/ui-ux-workflow-design-candidates.md` for full candidate analysis.
+
+**Recommendation: Two composing workflows**
+
+### Workflow B: UI/UX Design Creation Workflow
+For designing UI/UX from scratch. Adapted from `production-readiness-audit.json`.
+
+**Phase structure:**
+- Phase 0: Problem framing, user goals, constraints, existing design context (requireConfirmation always)
+- Phase 1: State 2-3 design directions with IA sketches (requireConfirmation — forces alternatives before convergence)
+- Phase 2: Freeze context packet + select reviewer families based on declared concerns
+- Phase 3: Parallel reviewer bundle (IA, UX laws, accessibility, edge cases, content/microcopy)
+- Phase 4: Synthesis + contradiction loop
+- Phase 5: Design spec handoff
+
+**Complexity branching**: Simple (single component, no new flows) skips Phases 1-3.
+
+### Workflow D: UI/UX Design Audit Workflow
+For reviewing an existing design description/spec before implementation. Adapted from `architecture-scalability-audit.json`.
+
+User provides design description; agent audits against declared dimensions: information architecture, Hick/Miller/Jakob/Fitts laws, accessibility (WCAG), edge cases (empty/error/loading/first-use), content/microcopy, visual hierarchy.
+
+**Composability**: Run B to create the design spec, then D to audit it before handing to implementation.
+
+## Decision Log
+
+- A (Minimal gate) rejected: only addresses 1 of 6 failure categories
+- C (Alternatives-first) incorporated as required step in B Phase 1, not standalone
+- B + D selected: B for creation, D for audit, different moments in design process
+- Challenge: reviewer generic findings — mitigated by context packet constraint
+- Challenge: too heavy — mitigated by Simple fast path
+
+## Final Summary
+
+**The core insight**: AI agents don't fail at UI/UX because they lack knowledge — they fail because nothing forces them through the process that converts knowledge into good design. The workflow's job is to make the right process structurally unavoidable.
+
+**What agents are bad at (6 categories):**
+1. Process — premature convergence on single solution, happy-path only
+2. UX law application — knows Hick/Miller/Jakob/Peak-End but skips them
+3. Content — designs layout, ignores microcopy and error states
+4. Accessibility — all 17 WCAG categories routinely missed
+5. Context — doesn't know design system, platform, brand
+6. Inherent — can't see/render, can't test with users
+
+**What a workflow can fix (categories 1-4):**
+Structural enforcement through phases, reviewer families, and requireConfirmation gates.
+
+**What requires human input (categories 5-6):**
+Design system, platform conventions, brand personality, real user research, visual review.
+
+**Residual risks:**
+- Reviewer families may produce generic findings without context packet constraint
+- Simple path may be overused — needs explicit criteria
+- Output is a spec, not a mockup — acceptable for developer-AI teams

package/docs/plans/ui-ux-workflow-review.md

@@ -0,0 +1,48 @@
+# UI/UX Workflow Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Fails if |
+|---|---|---|
+| Spec not mockup | Acceptable | Team needs visual approval before implementation — add external review checkpoint |
+| Context blindness | Acceptable | Agent proceeds without surfacing missing context — Phase 0 requireConfirmation handles this |
+| Simple path overuse | Acceptable | Agent misclassifies complex work as Simple — requireConfirmation on classification |
+
+## Failure Mode Review
+
+| Failure Mode | Risk | Coverage | Missing Mitigation |
+|---|---|---|---|
+| Generic reviewer findings | **High** | Partially | Reviewers must cite specific elements from the design description using frozen context packet |
+| Simple path overuse | Medium | Partially | requireConfirmation on complexity classification with explicit Simple criteria |
+| Wrong output format | Low | N/A | Not a workflow problem — addressed by how the spec is structured |
+
+**Highest risk: generic reviewer findings.** If reviewers produce platitudes ("consider grouping related items") instead of specific findings, the workflow produces the appearance of rigor without substance.
+
+## Runner-Up / Simpler Alternative Review
+
+- C (Alternatives-First) already incorporated as required step in B's hypothesis phase
+- Simpler variant (remove context packet phase) rejected — reviewers lose consistency without shared context
+- No hybrid opportunities
+
+## Philosophy Alignment
+
+All principles satisfied: make-illegal-states-unrepresentable, validate-at-boundaries, structured-freedom, errors-are-data, YAGNI (via Simple fast path). Minor acceptable tension on YAGNI resolved by Simple path.
+
+## Findings
+
+**Orange — Reviewer finding quality gate missing**
+Both B and D need explicit constraints that reviewer families must cite specific elements from the design description or context packet. Generic UX advice without reference to the actual design is a failing output, not a valid finding. Add to metaGuidance or reviewer instructions.
+
+**Yellow — Simple complexity criteria need explicit definition**
+"Simple" must be defined concretely in Phase 0: single component modification, no IA changes, no new user flows, no new interaction patterns. Without this, agents will self-classify to avoid rigor.
+
+## Recommended Revisions
+
+1. Add to reviewer family instructions: "Each finding must cite a specific element, component, or decision from the frozen context packet. Generic UX principles without specific reference are not findings."
+2. Define Simple explicitly: single component, no new flows, no IA changes, no new interaction patterns — everything else is Standard or Complex.
+3. Consider a `designVocabulary` section in the context packet: let the agent describe layout using structured prose terms (grid, card, list, modal, drawer, etc.) as a partial substitute for visual mockups.
+
+## Residual Concerns
+
+- The audit workflow (D) is most useful after B produces a spec — the workflow catalog should make this composability explicit in descriptions
+- Neither B nor D addresses the design system consistency problem (does this design match existing components?) — potential third workflow or reviewer family