qfai 1.7.8 → 1.7.13

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/00_index.md

@@ -6,20 +6,35 @@ Manifest of all UI/UX sidecar artifacts produced during a UI-bearing discussion.
 
 ## File Inventory
 
-| File                          | Purpose                                | Required |
-| ----------------------------- | -------------------------------------- | -------- |
-| 00_index.md                   | This manifest                          | Yes      |
-| 10_strategy.md                | Implementation strategy (YAML)         | Yes      |
-| 20_eval_axis_usability.md     | Usability evaluation axis              | Yes      |
-| 21_eval_axis_consistency.md   | Consistency evaluation axis            | Yes      |
-| 22_eval_axis_accessibility.md | Accessibility evaluation axis          | Yes      |
-| 23_eval_axis_delight.md       | Delight evaluation axis                | Yes      |
-| 30_comparison.md              | Option comparison against scoring axes | Yes      |
-| 31_anchor.md                  | Anchor screen selection rationale      | Yes      |
-| 40_contracts.md               | Screen interaction contracts           | Yes      |
-| 50_review_bundle.md           | Review input bundle                    | Yes      |
-| 60_critique_loop.md           | Critique loop tracking                 | Yes      |
+| File                                | Purpose                                     | Required |
+| ----------------------------------- | ------------------------------------------- | -------- |
+| 00_index.md                         | This manifest                               | Yes      |
+| 10_implementation_strategy.md       | Implementation strategy (canonical)         | Required |
+| 11_design_taste_interview.md        | Design taste interview (10 sections)        | Yes      |
+| 20_design_eval_invariant.md         | Invariant evaluation layer (3-layer)        | Yes      |
+| 21_design_eval_trend_derived.md     | Trend-derived evaluation layer (3-layer)    | Yes      |
+| 22_design_eval_product_specific.md  | Product-specific evaluation layer (3-layer) | Yes      |
+| 23_design_eval_aggregate.md         | Aggregate scoring layer (3-layer)           | Yes      |
+| 24_design_eval_dynamic_overrides.md | Dynamic evaluation overrides                | Optional |
+| 30_option_comparison.md             | Option comparison against scoring axes      | Yes      |
+| 31_selected_anchor_screen.md        | Selected anchor screen & direction decision | Yes      |
+| 40_screen_contracts.md              | Screen interaction contracts (11 fields)    | Yes      |
+| 50_review_input_bundle.md           | Review input bundle                         | Yes      |
 
 ## Completeness Rule
 
-All 11 files MUST be present for a UI-bearing pack. Partial generation is not permitted (BR-0026-0002).
+All required files (11 files) MUST be present for a UI-bearing pack. `24_design_eval_dynamic_overrides.md` is optional. Partial generation is not permitted (BR-0026-0002).
+
+## Forbidden Legacy Files
+
+The following files are NOT part of the canonical family and must NOT be created in new packs:
+
+- `30_comparison.md` — replaced by `30_option_comparison.md`
+- `31_anchor.md` — replaced by `31_selected_anchor_screen.md`
+- `40_contracts.md` — replaced by `40_screen_contracts.md`
+- `50_review_bundle.md` — replaced by `50_review_input_bundle.md`
+- `60_critique_loop.md` — removed (critique integrated into review bundle)
+- `20_eval_axis_usability.md` — replaced by 3-layer model
+- `21_eval_axis_consistency.md` — replaced by 3-layer model
+- `22_eval_axis_accessibility.md` — replaced by 3-layer model
+- `23_eval_axis_delight.md` — replaced by 3-layer model

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/10_implementation_strategy.md

@@ -0,0 +1,20 @@
+# Implementation Strategy
+
+## Strategy Definition
+
+<!-- Use exactly one canonical strategy block. -->
+
+### Strategy
+
+- surface: [web|mobile|desktop|cli|mixed|non-ui]
+- decision: [template|component-library|design-system|native-pattern|bespoke|none]
+- why_this_strategy: [Why this strategy is the right fit for the current product and surface]
+- expected_strengths: [Concrete strengths expected from this strategy]
+- known_risks: [Concrete risks, failure modes, or tradeoffs]
+- fit_for_this_product: [Why this strategy matches the actual product context]
+
+## Constraints
+
+- Use only the canonical enum values shown above.
+- Do not add legacy keys or freeform alternative enums.
+- Keep the strategy aligned with `01_Context.md` classification and `31_selected_anchor_screen.md`.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/11_design_taste_interview.md

@@ -0,0 +1,45 @@
+# Design Taste Interview
+
+## Purpose
+
+Structured interview to surface the design owner's taste preferences, aesthetic sensibilities, and quality expectations for this project.
+
+## visual_character
+
+<!-- Describe the visual identity: clean/bold/minimal/ornamental, color palette leanings, typography preferences -->
+
+## emotional_tone
+
+<!-- Describe the intended emotional response: professional/playful/serious/warm/neutral -->
+
+## anti_preferences
+
+<!-- List design patterns, styles, or approaches that should be explicitly avoided -->
+
+## admired_rejected_references
+
+<!-- Admired: products/designs that inspire. Rejected: anti-references to avoid -->
+
+## novelty_vs_safety
+
+<!-- Balance between innovative/novel and safe/conventional approaches -->
+
+## density_hierarchy
+
+<!-- Information density preferences: sparse/moderate/dense. Visual hierarchy approach -->
+
+## motion_material
+
+<!-- Motion design: minimal/functional/expressive. Material/depth: flat/layered/3D -->
+
+## brand_tone
+
+<!-- How brand voice manifests in UI: formal/casual, technical/accessible -->
+
+## unresolved_taste_questions
+
+<!-- Open questions about taste that need resolution during implementation -->
+
+## taste_reflection_depth
+
+<!-- Self-assessment: How well-defined is the taste direction? What needs more exploration? -->

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/20_design_eval_invariant.md

@@ -0,0 +1,68 @@
+# Evaluation Layer: Invariant
+
+## Layer Classification
+
+- Layer: invariant
+- Source: Universal UX heuristic (Nielsen)
+
+## Axes
+
+### Axis: [INV-01]
+
+- axis_id: INV-01
+- axis_name: [e.g., Learnability]
+- layer: invariant
+- origin: [e.g., Nielsen heuristic #2]
+- intent: [what this axis measures and why]
+- why_it_matters: [business/user impact of this axis]
+- score_scale: 1-5
+- score_anchors:
+  - low: [1 — description of poor performance]
+  - mid: [3 — description of acceptable performance]
+  - high: [5 — description of excellent performance]
+- positive_signals:
+  - [signal that indicates good performance on this axis]
+- negative_signals:
+  - [signal that indicates poor performance on this axis]
+- anti_patterns:
+  - [known anti-pattern to avoid]
+- evidence_required: [what evidence must be gathered to score this axis]
+- weight: [e.g., 0.20]
+- minimum_floor: [minimum acceptable score, e.g., 2]
+- source_refs:
+  - [reference to source material]
+- goal_refs:
+  - [reference to project goals this axis supports]
+- review_questions:
+  - [question a reviewer should ask when evaluating this axis]
+
+### Axis: [INV-02]
+
+<!-- Repeat the schema above for each invariant axis -->
+
+- axis_id: INV-02
+- axis_name: [e.g., Error Prevention]
+- layer: invariant
+- origin: [source]
+- intent: [what this measures]
+- why_it_matters: [impact]
+- score_scale: 1-5
+- score_anchors:
+  - low: [1 — poor]
+  - mid: [3 — acceptable]
+  - high: [5 — excellent]
+- positive_signals:
+  - [signal]
+- negative_signals:
+  - [signal]
+- anti_patterns:
+  - [pattern]
+- evidence_required: [evidence]
+- weight: [weight]
+- minimum_floor: [floor]
+- source_refs:
+  - [ref]
+- goal_refs:
+  - [ref]
+- review_questions:
+  - [question]

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/21_design_eval_trend_derived.md

@@ -0,0 +1,68 @@
+# Evaluation Layer: Trend-derived
+
+## Layer Classification
+
+- Layer: trend-derived
+- Source: Industry trend analysis and research synthesis
+
+## Axes
+
+### Axis: [TRD-01]
+
+- axis_id: TRD-01
+- axis_name: [e.g., Progressive Disclosure]
+- layer: trend-derived
+- origin: [research source / industry trend]
+- intent: [what this axis measures]
+- why_it_matters: [business/user impact]
+- score_scale: 1-5
+- score_anchors:
+  - low: [1 — description of poor performance]
+  - mid: [3 — description of acceptable performance]
+  - high: [5 — description of excellent performance]
+- positive_signals:
+  - [signal that indicates good performance]
+- negative_signals:
+  - [signal that indicates poor performance]
+- anti_patterns:
+  - [anti-pattern to avoid]
+- evidence_required: [what evidence must be gathered]
+- weight: [e.g., 0.15]
+- minimum_floor: [minimum acceptable score]
+- source_refs:
+  - [research source with freshness_date and confidence]
+- goal_refs:
+  - [project goal this axis supports]
+- review_questions:
+  - [question for reviewer]
+
+### Axis: [TRD-02]
+
+<!-- Repeat the schema above for each trend-derived axis -->
+
+- axis_id: TRD-02
+- axis_name: [axis name]
+- layer: trend-derived
+- origin: [source]
+- intent: [measurement intent]
+- why_it_matters: [impact]
+- score_scale: 1-5
+- score_anchors:
+  - low: [1 — poor]
+  - mid: [3 — acceptable]
+  - high: [5 — excellent]
+- positive_signals:
+  - [signal]
+- negative_signals:
+  - [signal]
+- anti_patterns:
+  - [pattern]
+- evidence_required: [evidence]
+- weight: [weight]
+- minimum_floor: [floor]
+- source_refs:
+  - [ref]
+- goal_refs:
+  - [ref]
+- review_questions:
+  - [question]

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/22_design_eval_product_specific.md

@@ -0,0 +1,68 @@
+# Evaluation Layer: Product-specific
+
+## Layer Classification
+
+- Layer: product-specific
+- Source: Project domain requirements and constraints
+
+## Axes
+
+### Axis: [PRD-01]
+
+- axis_id: PRD-01
+- axis_name: [e.g., Domain Workflow Fit]
+- layer: product-specific
+- origin: [domain requirement / stakeholder input]
+- intent: [what this axis measures]
+- why_it_matters: [business/user impact]
+- score_scale: 1-5
+- score_anchors:
+  - low: [1 — description of poor performance]
+  - mid: [3 — description of acceptable performance]
+  - high: [5 — description of excellent performance]
+- positive_signals:
+  - [signal that indicates good performance]
+- negative_signals:
+  - [signal that indicates poor performance]
+- anti_patterns:
+  - [anti-pattern to avoid]
+- evidence_required: [what evidence must be gathered]
+- weight: [e.g., 0.10]
+- minimum_floor: [minimum acceptable score]
+- source_refs:
+  - [domain requirement reference]
+- goal_refs:
+  - [project goal this axis supports]
+- review_questions:
+  - [question for reviewer]
+
+### Axis: [PRD-02]
+
+<!-- Repeat the schema above for each product-specific axis -->
+
+- axis_id: PRD-02
+- axis_name: [axis name]
+- layer: product-specific
+- origin: [source]
+- intent: [measurement intent]
+- why_it_matters: [impact]
+- score_scale: 1-5
+- score_anchors:
+  - low: [1 — poor]
+  - mid: [3 — acceptable]
+  - high: [5 — excellent]
+- positive_signals:
+  - [signal]
+- negative_signals:
+  - [signal]
+- anti_patterns:
+  - [pattern]
+- evidence_required: [evidence]
+- weight: [weight]
+- minimum_floor: [floor]
+- source_refs:
+  - [ref]
+- goal_refs:
+  - [ref]
+- review_questions:
+  - [question]

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/23_design_eval_aggregate.md

@@ -0,0 +1,41 @@
+# Evaluation Layer: Aggregate
+
+## Layer Classification
+
+- Layer: aggregate
+- Source: Weighted composite of all layer scores
+
+## Purpose
+
+This file defines how scores from invariant, trend-derived, and product-specific layers are combined into a single aggregate score for option comparison and decision-making.
+
+## Aggregate Scoring Rules
+
+- total_score_formula: weighted_sum(invariant \* layer_weights.invariant, trend \* layer_weights.trend_derived, product \* layer_weights.product_specific)
+- layer_weights:
+  - invariant: 0.60
+  - trend_derived: 0.25
+  - product_specific: 0.15
+- accept_threshold: 3.5
+- refine_band: 2.5-3.4
+- pivot_band: < 2.5
+- max_iterations: [maximum number of refine iterations before escalation]
+- plateau_rule: [rule for detecting score plateau across iterations, e.g., "3 consecutive iterations with delta < 0.1"]
+- missing_score_policy: [how to handle axes with no score, e.g., "exclude from weighted sum and note in review"]
+- disagreement_rule: [how to resolve disagreement between reviewers, e.g., "average scores, escalate if delta > 1.0"]
+
+## Scoring Guide
+
+- 5: Aggregate score >= 4.5 (accept with confidence)
+- 4: Aggregate score 3.5-4.4 (accept)
+- 3: Aggregate score 2.5-3.4 (refine)
+- 2: Aggregate score 1.5-2.4 (pivot recommended)
+- 1: Aggregate score < 1.5 (reject)
+
+## Cross-references
+
+- Invariant axes: `20_design_eval_invariant.md`
+- Trend-derived axes: `21_design_eval_trend_derived.md`
+- Product-specific axes: `22_design_eval_product_specific.md`
+- Dynamic overrides (optional): `24_design_eval_dynamic_overrides.md`
+- Option comparison: `30_option_comparison.md`

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/24_design_eval_dynamic_overrides.md

@@ -0,0 +1,28 @@
+# Dynamic Evaluation Overrides
+
+## Purpose
+
+Project-specific overrides and extensions to the standard 3-layer evaluation model.
+Used when default invariant/trend-derived/product-specific axes need adjustment for this project's unique context.
+
+## Override Rules
+
+| Override Type     | Description                                  | Approval Required |
+| ----------------- | -------------------------------------------- | ----------------- |
+| Weight adjustment | Change default layer weights                 | Yes               |
+| Axis suppression  | Suppress a default axis (with justification) | Yes               |
+| Custom axis       | Add a project-specific evaluation axis       | No                |
+| Threshold change  | Modify accept/refine/pivot thresholds        | Yes               |
+
+## Active Overrides
+
+<!-- List active overrides below. Each must include justification and approval reference. -->
+
+| Axis / Rule | Override | Justification | Approved By |
+| ----------- | -------- | ------------- | ----------- |
+| (none)      | —        | —             | —           |
+
+## Constraint
+
+- Overrides must not remove invariant-layer axes without a Decision Record (DR).
+- All overrides must be traceable to a specific project requirement or stakeholder decision.

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/30_option_comparison.md

@@ -0,0 +1,56 @@
+# Option Comparison
+
+## Purpose
+
+Compare 2–3 design options against 3-layer scoring axes to support direction selection.
+Selected anchor details are in `31_selected_anchor_screen.md`.
+
+## Comparison Matrix
+
+### Invariant Axes
+
+| axis_id | axis_name | layer     | Option A: [Name] | Option B: [Name] | rationale   |
+| ------- | --------- | --------- | ---------------- | ---------------- | ----------- |
+| INV-01  | [name]    | invariant | [score 1-5]      | [score 1-5]      | [rationale] |
+| INV-02  | [name]    | invariant | [score 1-5]      | [score 1-5]      | [rationale] |
+
+### Trend-derived Axes
+
+| axis_id | axis_name | layer         | Option A: [Name] | Option B: [Name] | rationale         |
+| ------- | --------- | ------------- | ---------------- | ---------------- | ----------------- |
+| TRD-01  | [name]    | trend-derived | [score 1-5]      | [score 1-5]      | [source + reason] |
+
+### Product-specific Axes
+
+| axis_id | axis_name | layer            | Option A: [Name] | Option B: [Name] | rationale   |
+| ------- | --------- | ---------------- | ---------------- | ---------------- | ----------- |
+| PRD-01  | [name]    | product-specific | [score 1-5]      | [score 1-5]      | [rationale] |
+
+## Aggregate Scoring
+
+| Option   | Weights                               | Normalized Total | Threshold             | Rank   |
+| -------- | ------------------------------------- | ---------------- | --------------------- | ------ |
+| Option A | Invariant: 60%, Trend: 25%, Prod: 15% | [total]          | [accept/refine/pivot] | [rank] |
+| Option B | Invariant: 60%, Trend: 25%, Prod: 15% | [total]          | [accept/refine/pivot] | [rank] |
+
+## Per-Option Summary
+
+### Option A: [Name]
+
+- Strengths: [key strengths from scoring]
+- Weaknesses: [key weaknesses from scoring]
+- Risk: [key risks if selected]
+- Defer reason: [why this option might be deferred, or N/A]
+
+### Option B: [Name]
+
+- Strengths: [key strengths from scoring]
+- Weaknesses: [key weaknesses from scoring]
+- Risk: [key risks if selected]
+- Defer reason: [why this option might be deferred, or N/A]
+
+## Cross-references
+
+- 3-layer evaluation files: `20_design_eval_invariant.md`, `21_design_eval_trend_derived.md`, `22_design_eval_product_specific.md`, `23_design_eval_aggregate.md`
+- 3-layer model & aggregate rules: `23_design_eval_aggregate.md` (Aggregate Scoring Rules section)
+- Selected anchor & adoption rationale: `31_selected_anchor_screen.md`

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/31_selected_anchor_screen.md

@@ -0,0 +1,42 @@
+# Selected Anchor Screen
+
+## Purpose
+
+Document the selected design option, anchor screen, adoption rationale, and rejected/deferred options.
+This file is the canonical record of the design direction decision.
+
+## Selection
+
+- selected_option: [Option X from 30_option_comparison.md]
+- selected_anchor_screen: [Primary screen that anchors the design direction, e.g., Dashboard, Listing, Detail]
+- why_selected: [Rationale for selection based on scores, constraints, and project context]
+
+## Rejected or Deferred Options
+
+### [Option Y]
+
+- disposition: [rejected|deferred]
+- reason: [Why this option was not selected]
+- conditions_for_reconsideration: [Under what circumstances this option could be revisited, or N/A]
+
+### [Option Z]
+
+- disposition: [rejected|deferred]
+- reason: [Why this option was not selected]
+- conditions_for_reconsideration: [Under what circumstances this option could be revisited, or N/A]
+
+## Implementation Guardrails
+
+- [Guardrail 1: constraint or principle that must be maintained during implementation]
+- [Guardrail 2: boundary condition or quality bar]
+
+## Reviewer Focus
+
+- [Key area 1 the reviewer should pay attention to]
+- [Key area 2 the reviewer should verify against the scoring rationale]
+
+## Cross-references
+
+- Option comparison: `30_option_comparison.md`
+- Strategy: `10_implementation_strategy.md`
+- Screen contracts: `40_screen_contracts.md`

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/40_screen_contracts.md

@@ -0,0 +1,44 @@
+# Screen Contracts
+
+## Purpose
+
+Draft interaction contracts for key screens using the strong screen contract schema (11 required fields).
+
+### Screen: [Screen Name]
+
+- screen_id: SCR-001
+- route: /path-to-screen
+- purpose: [what the user accomplishes on this screen]
+- actor: [primary user role]
+- primary_tasks:
+  - [task 1: trigger → success criteria]
+  - [task 2: trigger → success criteria]
+- secondary_tasks:
+  - [secondary task 1: trigger → success criteria]
+  - [secondary task 2: trigger → success criteria]
+- required_states:
+  - default: [default/empty state description]
+  - loading: [loading indicator description]
+  - empty: [empty state description]
+  - error: [error message + retry CTA description]
+- transitions:
+  - empty → loading: [data fetch initiated]
+  - loading → default: [data received and primary content is ready]
+  - loading → error: [fetch failure]
+  - error → loading: [retry action]
+- observable_outcomes:
+  - [expected user outcome → verification method]
+  - [expected system behavior → verification method]
+- notes_for_verify: [notes for verification/testing]
+- notes_for_reviewer: [any additional context for the reviewer]
+
+<!-- Nested list format is canonical for primary_tasks, secondary_tasks, required_states, transitions, observable_outcomes. Inline CSV is accepted for backward compatibility. -->
+
+> **Note:** `required_states` primary truth lives in this file. Each screen's state set is authoritative here.
+> **Note:** `secondary_tasks` documents non-primary user workflows available on the screen.
+> Layout specification is optional and should be added as notes only.
+
+## Cross-references
+
+- Selected anchor: `31_selected_anchor_screen.md`
+- Option comparison: `30_option_comparison.md`

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/50_review_input_bundle.md

@@ -0,0 +1,36 @@
+# Review Input Bundle
+
+## Purpose
+
+Consolidate all sidecar artifacts into a review-ready bundle for design reviewers.
+
+## Bundle Contents
+
+| Artifact                   | Path                                       | Status                    |
+| -------------------------- | ------------------------------------------ | ------------------------- |
+| Strategy                   | `uiux/10_implementation_strategy.md`       | [draft/reviewed/approved] |
+| Taste interview            | `uiux/11_design_taste_interview.md`        | [draft/reviewed/approved] |
+| Trend scan                 | `04_Sources.md#Trend Scan`                 | [draft/reviewed/approved] |
+| Invariant layer            | `uiux/20_design_eval_invariant.md`         | [draft/reviewed/approved] |
+| Trend-derived layer        | `uiux/21_design_eval_trend_derived.md`     | [draft/reviewed/approved] |
+| Product-specific layer     | `uiux/22_design_eval_product_specific.md`  | [draft/reviewed/approved] |
+| Aggregate layer            | `uiux/23_design_eval_aggregate.md`         | [draft/reviewed/approved] |
+| Dynamic overrides          | `uiux/24_design_eval_dynamic_overrides.md` | [optional]                |
+| Option comparison          | `uiux/30_option_comparison.md`             | [draft/reviewed/approved] |
+| Selected anchor            | `uiux/31_selected_anchor_screen.md`        | [draft/reviewed/approved] |
+| Screen contracts           | `uiux/40_screen_contracts.md`              | [draft/reviewed/approved] |
+| Prototyping recommendation | `../prototyping.yaml`                      | [draft/reviewed/approved] |
+
+## Trend-derived review focus
+
+- Required trend categories are all present and complete.
+- Stale / overused AI slop patterns are explicitly avoided.
+- Trend research is translated into scoring, comparison, and selected anchor decisions.
+
+## Review Checklist
+
+- [ ] Strategy aligns with surface type and project constraints
+- [ ] Trend categories are complete and translated into local design decisions
+- [ ] Competitive references include adopted_points, rejected_points, and local_translation
+- [ ] Selected anchor clearly documents rationale and downstream implications
+- [ ] Screen contracts cover all required states