qfai 1.7.13 → 1.7.15

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/discussion-completion-matrix.md

@@ -0,0 +1,26 @@
+# Discussion Completion Matrix
+
+Use this file for the full completion logic behind `/qfai-discussion`.
+
+## UI-bearing Packs
+
+Completion is blocked until all are true:
+
+1. Strategy selected
+2. Design taste interview completed
+3. 3-layer scoring family completed
+4. Dynamic overrides documented
+5. Option comparison completed
+6. Selected anchor documented
+7. Screen contracts drafted
+
+## Non-UI Packs
+
+- No uiux sidecars required
+- No additional UI-bearing completion conditions apply
+- `prototyping.yaml` is not required
+
+## Notes
+
+- HTML+CSS mock is optional fallback only.
+- Behavior obligations remain primary.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/discussion-coverage-checklist.md

@@ -0,0 +1,20 @@
+# Discussion Coverage Checklist
+
+Use this file when checking whether `/qfai-discussion` covered the required topics.
+
+## Required Topics
+
+1. Product concept and target users
+2. Scope boundary and anti-goals
+3. User stories and user flows
+4. Functional requirements with source traceability
+5. Non-functional requirements with measurable targets
+6. Performance constraints and SLO assumptions
+7. Security constraints and risk controls
+8. Domain glossary consistency
+9. Technical and operational constraints
+10. Project policies
+
+## Completion Rule
+
+- Missing topics must become explicit OQ or deferred items.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/example-mapping-guide.md

@@ -0,0 +1,18 @@
+# Example Mapping Guide
+
+Use this file when `/qfai-discussion` performs Example Mapping.
+
+## Minimum Perspectives
+
+1. Happy path
+2. Negative path
+3. Edge or boundary
+4. Permission or role
+5. State transition when stateful
+6. Idempotency or retry when external I/O exists
+
+## Rules
+
+- Use perspective coverage as the gate, not raw case counts.
+- Mark intentionally skipped perspectives with reason and follow-up.
+- Feed unresolved seeds into OQ items with owner and decision point.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/oq-and-deferred-rules.md

@@ -0,0 +1,41 @@
+# OQ and Deferred Rules
+
+Use this file for canonical field definitions in `/qfai-discussion`.
+
+## OQ Register Fields
+
+- `OQ-ID`
+- `Title`
+- `Gate`
+- `Disposition`
+- `Owner`
+- `Rationale`
+- `Options`
+- `Recommendation`
+- `Next-Decision-Point`
+- `Due`
+- `Evidence`
+
+## Gate Enum
+
+`discussion|sdd|atdd|tdd|ops`
+
+## Deferred Fields
+
+- `OQ-ID`
+- `Title`
+- `Gate`
+- `Deferred-Reason`
+- `Deferred-Until`
+- `Owner`
+- `Due`
+- `Severity`
+- `Impact`
+- `Mitigation`
+- `Evidence`
+
+## Guardrails
+
+- Do not leave recommendations implicit.
+- Do not defer without a next decision point.
+- Do not close the pack while `Disposition: open` remains.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/review-cycle-playbook.md

@@ -0,0 +1,22 @@
+# Discussion Review Cycle Playbook
+
+Use this file for detailed review-pack handling in `/qfai-discussion`.
+
+## Required Artifacts
+
+- `review_request.md`
+- `Rxx_<reviewer>.md`
+- `summary.json`
+
+## Cycle Rules
+
+1. Create a new review pack for each cycle.
+2. Apply the footer SSOT from `rcp_footer.md`.
+3. Run only the routed reviewers for the current phase and conditions.
+4. On `FAIL`, rerun only the failed reviewer and any reviewer whose scope changed.
+5. Mark fixed only when all routed blocking reviewers are `PASS`.
+
+## summary.json
+
+- `target.kind` must be `"discussion"`.
+- Keep rerun history append-only.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/ui-bearing-playbook.md

@@ -0,0 +1,50 @@
+# UI-bearing Playbook
+
+Use this file when `/qfai-discussion` needs the full UI-bearing decision logic.
+
+## Classification Rule
+
+- Classify by surface type, not by interaction complexity.
+
+## Surface Mapping
+
+| Surface | UI-bearing | Result                            |
+| ------- | ---------- | --------------------------------- |
+| web     | Yes        | Generate full uiux sidecar family |
+| mobile  | Yes        | Generate full uiux sidecar family |
+| desktop | Yes        | Generate full uiux sidecar family |
+| cli     | Yes        | Generate full uiux sidecar family |
+| mixed   | Yes        | Generate full uiux sidecar family |
+| non-ui  | No         | Skip uiux sidecars                |
+
+## Detection Signals
+
+- Explicit classification in `01_Context.md`
+- UI-oriented stories in `03_Story-Workshop.md`
+- Mermaid screen flows
+- HTML or visual structure hints as supporting signals only
+
+## Sidecar Family SSOT
+
+- `uiux/00_index.md`
+- `uiux/10_implementation_strategy.md`
+- `uiux/11_design_taste_interview.md`
+- `uiux/12_design_system.md`
+- `uiux/20_design_eval_invariant.md`
+- `uiux/21_design_eval_trend_derived.md`
+- `uiux/22_design_eval_product_specific.md`
+- `uiux/23_design_eval_aggregate.md`
+- `uiux/24_design_eval_dynamic_overrides.md`
+- `uiux/30_option_comparison.md`
+- `uiux/31_selected_anchor_screen.md`
+- `uiux/40_screen_contracts.md`
+- `uiux/50_review_input_bundle.md`
+
+### Trend Scan SSOT
+
+Trend Scan is **not** a sidecar file. Trend Scan lives at
+`04_Sources.md#Trend Scan` (part of the core 15-file discussion pack).
+The legacy `uiux/20_trend_scan.md` template was removed; `uiux/20_design_eval_invariant.md`
+is a different axis family (design evaluation invariant criteria) and does
+not own Trend Scan content. UI-bearing completion checks read Trend Scan
+from `04_Sources.md`.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/ui_ux/platform_baselines.md

@@ -0,0 +1,107 @@
+# UI/UX Platform Baselines
+
+Use this file only when the current discussion needs platform-specific detail.
+
+## Cross-Platform Baseline
+
+- Keep the same conceptual model across surfaces.
+- Do not force the same layout across mobile, desktop, and CLI.
+- Document intentional platform deviations.
+- Shared design tokens are preferred, but interaction patterns should stay platform-native.
+
+## Web
+
+### Use when
+
+- Browser-based product with responsive layouts, forms, or complex navigation.
+
+### Baseline expectations
+
+- Keyboard navigation works end to end.
+- Focus indicators remain visible.
+- Contrast meets WCAG expectations.
+- Navigation changes across breakpoints intentionally.
+- Hover-only interaction is never the only path.
+
+### Practical floor
+
+- Minimum target size: 24x24 CSS px at WCAG 2.2 AA floor; prefer 44x44 CSS px.
+- Common layout bands:
+  - compact: 0-599 px
+  - medium: 600-839 px
+  - expanded: 840-1199 px
+  - large: 1200 px+
+
+## Mobile
+
+### Shared mobile rules
+
+- Primary actions should sit in reachable zones.
+- Avoid surprise horizontal scroll.
+- Respect safe areas and system gestures.
+- Every gesture-only action needs a visible alternative when feasible.
+
+### iOS
+
+- Prefer standard navigation bar, tab bar, modal, and back behavior.
+- Minimum touch target: 44x44 pt.
+- Support Dynamic Type where the surface expects it.
+- Respect swipe-back and safe area behavior.
+
+### Android
+
+- Prefer Material-aligned navigation patterns and system back behavior.
+- Minimum touch target: 48x48 dp.
+- Use bottom navigation only for 3-5 primary destinations.
+- Do not import iOS-only interaction idioms without strong reason.
+
+## Desktop
+
+### Shared desktop rules
+
+- Keyboard efficiency matters more than on mobile.
+- Dense information layouts are acceptable if hierarchy stays clear.
+- Windowing, focus, and menu behavior should feel native.
+
+### Windows
+
+- Respect system theme and high-contrast support.
+- Do not break expected title-bar or window-management behavior.
+- Pointer-friendly controls may be smaller than touch controls, but touch mode should still be usable.
+
+### macOS
+
+- Preserve standard menu, shortcut, and window expectations.
+- Avoid modal-heavy flows where non-modal inspection is more natural.
+- Do not break standard copy/paste/undo/find conventions.
+
+## CLI
+
+- Optimize for scanability and command confidence.
+- Keep output structured and predictable.
+- Use concise labels, clear status, and recoverable error messages.
+- Color must not be the only meaning carrier.
+- Important actions should remain discoverable without memorizing hidden flags.
+
+## States
+
+Every key surface should account for:
+
+- default
+- loading
+- empty
+- error
+- success or completion confirmation when relevant
+
+## Dark Mode
+
+- Treat dark mode as a separate design pass, not an inversion.
+- Re-check contrast, semantic colors, overlays, and images.
+- Avoid pure black unless the product explicitly needs it.
+
+## Motion
+
+- Typical UI transitions should stay short and purposeful.
+- Prefer roughly 100-300 ms for common transitions.
+- Respect reduced-motion preferences.
+- Motion should explain change, not delay access.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/ui_ux/review_audit_playbook.md

@@ -0,0 +1,104 @@
+# UI/UX Review Audit Playbook
+
+Use this file when the core checklist is not enough.
+
+## Heuristic Review Pass
+
+Review the design direction against these durable heuristics:
+
+- system status is visible
+- product language matches user language
+- users can cancel, go back, undo, or recover
+- terms and patterns are consistent
+- error-prone input is constrained or prevented
+- users recognize options instead of recalling them
+- novice and expert use are both supported where relevant
+- unnecessary noise is removed
+- errors explain recovery
+- help is contextual and task-oriented
+
+## Layout And Information Architecture
+
+Check for:
+
+- a clear reading path
+- meaningful grouping and spacing
+- obvious hierarchy
+- limited top-level navigation choices
+- shallow nesting
+- no dead-end screens
+- no false bottoms or hidden overflow
+
+## Forms And Actions
+
+Check for:
+
+- visible labels
+- appropriate input types
+- inline validation near the source
+- preserved input on error
+- descriptive action labels
+- one clear primary action
+- destructive actions separated from constructive actions
+
+## Screen States
+
+Each important screen should specify:
+
+- what empty means
+- what loading looks like
+- what a recoverable error says
+- how the user retries or exits
+- whether success needs confirmation or summary
+
+## Accessibility Audit
+
+Check for:
+
+- keyboard access
+- visible focus
+- heading and landmark clarity
+- non-color cues
+- adequate target size
+- readable copy
+- screen-reader-compatible semantics where custom UI exists
+
+Note:
+
+- automated accessibility tools catch only part of the problem;
+- manual keyboard and screen-reader review is still required.
+
+## Anti-Pattern Red Flags
+
+Flag immediately if you see:
+
+- mystery-meat navigation
+- placeholder-only labels
+- premature or submit-only validation
+- broken back behavior
+- invisible navigation
+- silent failure
+- blocking full-screen spinners
+- tiny touch targets
+- gesture-only critical actions
+- manipulative dark patterns
+
+## Documentation Expectations For QFAI
+
+A good discussion artifact should make these reviewable without guesswork:
+
+- screen inventory or equivalent key-surface coverage
+- flow logic including error paths
+- component or interaction inventory where it matters
+- responsive/adaptive behavior where the surface changes materially
+- accessibility constraints
+- decision rationale and rejected options
+
+## Recommended Audit Order
+
+1. Validate user goal and flow.
+2. Validate option comparison and anchor choice.
+3. Validate state coverage and contracts.
+4. Validate accessibility and platform fit.
+5. Validate anti-pattern absence.
+6. Validate traceability into `04_Sources.md`, `14_Review-Request.md`, and `99_delta.md`.

package/assets/init/.qfai/assistant/skills/qfai-discussion/references/ui_ux/trend_scan_playbook.md

@@ -0,0 +1,76 @@
+# UI/UX Trend Scan Playbook
+
+Do not hard-code year-specific design trends into the core reference.
+Use this playbook to research and translate current signals during each discussion run.
+
+## Goal
+
+Produce trend input that informs design direction without replacing product reasoning.
+
+## Required Output Shape
+
+When UI-bearing, `04_Sources.md` trend entries should capture:
+
+- reference
+- observation
+- decision_connection
+- evaluation_connection
+- local_implication
+
+## Required Research Categories
+
+At minimum, check the categories that materially affect the surface:
+
+- navigation patterns
+- density and layout
+- motion and transitions
+- color and theming
+- form interaction
+- accessibility-sensitive interaction changes
+- AI-assisted or multimodal interaction, if relevant
+- platform release guidance, if the surface depends on native conventions
+
+## Freshness Rules
+
+- Prefer official platform guidance and recent primary sources.
+- Treat trend claims as volatile unless supported by current evidence.
+- If a claim is older or weakly supported, record it as low-confidence or omit it.
+
+## Translation Rules
+
+Do not stop at "this is trendy."
+Always translate a reference into:
+
+- whether it fits the product's users and task frequency;
+- whether it improves or harms clarity;
+- whether it changes scoring in `uiux/20-24`;
+- whether it affects the selected anchor or contracts;
+- whether it should be adopted, adapted, or rejected.
+
+## Rejection Rules
+
+Reject a trend when:
+
+- it conflicts with usability or accessibility floors;
+- it depends on a platform convention the product does not have;
+- it adds novelty without improving the core task;
+- it increases cognitive load for a routine workflow;
+- it is fashionable but weakly evidenced.
+
+## Competitive Reference Registry Expectations
+
+For each meaningful competitor or reference pattern, capture:
+
+- what was adopted
+- what was rejected
+- how adopted ideas were translated locally
+
+Avoid placeholders such as `TBD`, `N/A`, `TODO`, or empty values.
+
+## Good Trend Scan Questions
+
+- What behavior is actually becoming standard?
+- Which surfaces are adopting it successfully?
+- What problem does it solve?
+- What tradeoff does it introduce?
+- Should QFAI adopt it directly, adapt it, or explicitly reject it?