@monoes/monomindcli 2.15.3 → 2.15.4

package/org-skills/ux-researcher-designer/references/usability-testing-frameworks.md

@@ -0,0 +1,412 @@
+# Usability Testing Frameworks
+
+Reference for planning and conducting usability tests that produce actionable insights.
+
+---
+
+## Table of Contents
+
+- [Testing Methods Overview](#testing-methods-overview)
+- [Test Planning](#test-planning)
+- [Task Design](#task-design)
+- [Moderation Techniques](#moderation-techniques)
+- [Analysis Framework](#analysis-framework)
+- [Reporting Template](#reporting-template)
+
+---
+
+## Testing Methods Overview
+
+### Method Selection Matrix
+
+| Method | When to Use | Participants | Time | Output |
+|--------|-------------|--------------|------|--------|
+| Moderated remote | Deep insights, complex flows | 5-8 | 45-60 min | Rich qualitative |
+| Unmoderated remote | Quick validation, simple tasks | 10-20 | 15-20 min | Quantitative + video |
+| In-person | Physical products, context matters | 5-10 | 60-90 min | Very rich qualitative |
+| Guerrilla | Quick feedback, public spaces | 3-5 | 5-10 min | Rapid insights |
+| A/B testing | Comparing two designs | 100+ | Varies | Statistical data |
+
+### Participant Count Guidelines
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    FINDING USABILITY ISSUES                 │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  % Issues Found                                             │
+│  100% ┤                          ●────●────●                │
+│   90% ┤                    ●─────                           │
+│   80% ┤              ●─────                                 │
+│   75% ┤         ●────                 ← 5 users: 75-80%     │
+│   50% ┤    ●────                                            │
+│   25% ┤ ●──                                                 │
+│    0% ┼────┬────┬────┬────┬────┬────                       │
+│        1    2    3    4    5    6+   Users                  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Nielsen's Rule:** 5 users find ~75-80% of usability issues
+
+| Goal | Participants | Reasoning |
+|------|--------------|-----------|
+| Find major issues | 5 | 80% coverage, diminishing returns |
+| Validate fix | 3 | Confirm specific issue resolved |
+| Compare designs | 8-10 per design | Need comparison data |
+| Quantitative metrics | 20+ | Statistical significance |
+
+---
+
+## Test Planning
+
+### Research Questions
+
+Transform vague goals into testable questions:
+
+| Vague Goal | Testable Question |
+|------------|-------------------|
+| "Is it easy to use?" | "Can users complete checkout in under 3 minutes?" |
+| "Do users like it?" | "Will users choose Design A or B for this task?" |
+| "Does it make sense?" | "Can users find the settings without hints?" |
+
+### Test Plan Template
+
+```
+PROJECT: _______________
+DATE: _______________
+RESEARCHER: _______________
+
+RESEARCH QUESTIONS:
+1. _______________
+2. _______________
+3. _______________
+
+PARTICIPANTS:
+• Target: [Persona or user type]
+• Count: [Number]
+• Recruitment: [Source]
+• Incentive: [Amount/type]
+
+METHOD:
+• Type: [Moderated/Unmoderated/Remote/In-person]
+• Duration: [Minutes per session]
+• Environment: [Tool/Location]
+
+TASKS:
+1. [Task description + success criteria]
+2. [Task description + success criteria]
+3. [Task description + success criteria]
+
+METRICS:
+• Completion rate (target: __%)
+• Time on task (target: __ min)
+• Error rate (target: __%)
+• Satisfaction (target: __/5)
+
+SCHEDULE:
+• Pilot: [Date]
+• Sessions: [Date range]
+• Analysis: [Date]
+• Report: [Date]
+```
+
+### Pilot Testing
+
+**Always pilot before real sessions:**
+
+- Run 1-2 test sessions with team members
+- Check task clarity and timing
+- Test recording/screen sharing
+- Adjust based on pilot feedback
+
+**Pilot Checklist:**
+- [ ] Tasks understood without clarification
+- [ ] Session fits in time slot
+- [ ] Recording captures screen + audio
+- [ ] Post-test questions make sense
+
+---
+
+## Task Design
+
+### Good vs. Bad Tasks
+
+| Bad Task | Why Bad | Good Task |
+|----------|---------|-----------|
+| "Find the settings" | Leading | "Change your notification preferences" |
+| "Use the dashboard" | Vague | "Find how many sales you made last month" |
+| "Click the blue button" | Prescriptive | "Submit your order" |
+| "Do you like this?" | Opinion-based | "Rate how easy it was (1-5)" |
+
+### Task Construction Formula
+
+```
+SCENARIO + GOAL + SUCCESS CRITERIA
+
+Scenario: Context that makes task realistic
+Goal: What user needs to accomplish
+Success: How we know they succeeded
+
+Example:
+"Imagine you're planning a trip to Paris next month. [SCENARIO]
+Book a hotel for 3 nights in your budget. [GOAL]
+You've succeeded when you see the confirmation page. [SUCCESS]"
+```
+
+### Task Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| Exploration | First impressions | "Look around and tell me what you think this does" |
+| Specific | Core functionality | "Add item to cart and checkout" |
+| Comparison | Design validation | "Which of these two menus would you use to..." |
+| Stress | Edge cases | "What would you do if your payment failed?" |
+
+### Task Difficulty Progression
+
+Start easy, increase difficulty:
+
+```
+Task 1: Warm-up (easy, builds confidence)
+Task 2: Core flow (main functionality)
+Task 3: Secondary flow (important but less common)
+Task 4: Edge case (stress test)
+Task 5: Free exploration (open-ended)
+```
+
+---
+
+## Moderation Techniques
+
+### The Think-Aloud Protocol
+
+**Instruction Script:**
+"As you work through the tasks, please think out loud. Tell me what you're looking at, what you're thinking, and what you're trying to do. There are no wrong answers - we're testing the design, not you."
+
+**Prompts When Silent:**
+- "What are you thinking right now?"
+- "What do you expect to happen?"
+- "What are you looking for?"
+- "Tell me more about that"
+
+### Handling Common Situations
+
+| Situation | What to Say |
+|-----------|-------------|
+| User asks for help | "What would you do if I weren't here?" |
+| User is stuck | "What are your options?" (wait 30 sec before hint) |
+| User apologizes | "You're doing great. We're testing the design." |
+| User goes off-task | "That's interesting. Let's come back to [task]." |
+| User criticizes | "Tell me more about that." (neutral, don't defend) |
+
+### Non-Leading Question Techniques
+
+| Leading (Don't) | Neutral (Do) |
+|-----------------|--------------|
+| "Did you find that confusing?" | "How was that experience?" |
+| "The search is over here" | "What do you think you should do?" |
+| "Don't you think X is easier?" | "Which do you prefer and why?" |
+| "Did you notice the tooltip?" | "What happened there?" |
+
+### Post-Task Questions
+
+After each task:
+1. "How difficult was that?" (1-5 scale)
+2. "What, if anything, was confusing?"
+3. "What would you improve?"
+
+After all tasks:
+1. "What stood out to you?"
+2. "What was the best/worst part?"
+3. "Would you use this? Why/why not?"
+
+---
+
+## Analysis Framework
+
+### Severity Rating Scale
+
+| Severity | Definition | Criteria |
+|----------|------------|----------|
+| 4 - Critical | Prevents task completion | User cannot proceed |
+| 3 - Major | Significant difficulty | User struggles, considers giving up |
+| 2 - Minor | Causes hesitation | User recovers independently |
+| 1 - Cosmetic | Noticed but not problematic | User comments but unaffected |
+
+### Issue Documentation Template
+
+```
+ISSUE ID: ___
+SEVERITY: [1-4]
+FREQUENCY: [X/Y participants]
+
+TASK: [Which task]
+TIMESTAMP: [When in session]
+
+OBSERVATION:
+[What happened - factual description]
+
+USER QUOTE:
+"[Direct quote if available]"
+
+HYPOTHESIS:
+[Why this might be happening]
+
+RECOMMENDATION:
+[Proposed solution]
+
+AFFECTED PERSONA:
+[Which user types]
+```
+
+### Pattern Recognition
+
+**Quantitative Signals:**
+- Task completion rate < 80%
+- Time on task > 2x expected
+- Error rate > 20%
+- Satisfaction < 3/5
+
+**Qualitative Signals:**
+- Same confusion point across 3+ users
+- Repeated verbal frustration
+- Workaround attempts
+- Feature requests during task
+
+### Analysis Matrix
+
+```
+┌─────────────────┬───────────┬───────────┬───────────┐
+│ Issue           │ Frequency │ Severity  │ Priority  │
+├─────────────────┼───────────┼───────────┼───────────┤
+│ Can't find X    │ 4/5       │ Critical  │ HIGH      │
+│ Confusing label │ 3/5       │ Major     │ HIGH      │
+│ Slow loading    │ 2/5       │ Minor     │ MEDIUM    │
+│ Typo in text    │ 1/5       │ Cosmetic  │ LOW       │
+└─────────────────┴───────────┴───────────┴───────────┘
+
+Priority = Frequency × Severity
+```
+
+---
+
+## Reporting Template
+
+### Executive Summary
+
+```
+USABILITY TEST REPORT
+[Project Name] | [Date]
+
+OVERVIEW
+• Participants: [N] users matching [persona]
+• Method: [Type of test]
+• Tasks: [N] tasks covering [scope]
+
+KEY FINDINGS
+1. [Most critical issue + impact]
+2. [Second issue]
+3. [Third issue]
+
+SUCCESS METRICS
+• Completion rate: [X]% (target: Y%)
+• Avg. time on task: [X] min (target: Y min)
+• Satisfaction: [X]/5 (target: Y/5)
+
+TOP RECOMMENDATIONS
+1. [Highest priority fix]
+2. [Second priority]
+3. [Third priority]
+```
+
+### Detailed Findings Section
+
+```
+FINDING 1: [Title]
+
+Severity: [Critical/Major/Minor/Cosmetic]
+Frequency: [X/Y participants]
+Affected Tasks: [List]
+
+What Happened:
+[Description of the problem]
+
+Evidence:
+• P1: "[Quote]"
+• P3: "[Quote]"
+• [Video timestamp if available]
+
+Impact:
+[How this affects users and business]
+
+Recommendation:
+[Proposed solution with rationale]
+
+Design Mockup:
+[Optional: before/after if applicable]
+```
+
+### Metrics Dashboard
+
+```
+TASK PERFORMANCE SUMMARY
+
+Task 1: [Name]
+├─ Completion: ████████░░ 80%
+├─ Avg. Time: 2:15 (target: 2:00)
+├─ Errors: 1.2 avg
+└─ Satisfaction: ★★★★☆ 4.2/5
+
+Task 2: [Name]
+├─ Completion: ██████░░░░ 60% ⚠️
+├─ Avg. Time: 4:30 (target: 3:00) ⚠️
+├─ Errors: 3.1 avg ⚠️
+└─ Satisfaction: ★★★☆☆ 3.1/5
+
+[Continue for all tasks]
+```
+
+---
+
+## Quick Reference
+
+### Session Checklist
+
+**Before Session:**
+- [ ] Test plan finalized
+- [ ] Tasks written and piloted
+- [ ] Recording set up and tested
+- [ ] Consent form ready
+- [ ] Prototype/product accessible
+- [ ] Note-taking template ready
+
+**During Session:**
+- [ ] Consent obtained
+- [ ] Think-aloud explained
+- [ ] Recording started
+- [ ] Tasks presented one at a time
+- [ ] Post-task ratings collected
+- [ ] Debrief questions asked
+- [ ] Thanks and incentive
+
+**After Session:**
+- [ ] Notes organized
+- [ ] Recording saved
+- [ ] Initial impressions captured
+- [ ] Issues logged
+
+### Common Metrics
+
+| Metric | Formula | Target |
+|--------|---------|--------|
+| Completion rate | Successful / Total × 100 | >80% |
+| Time on task | Average seconds | <2x expected |
+| Error rate | Errors / Attempts × 100 | <15% |
+| Task-level satisfaction | Average rating | >4/5 |
+| SUS score | Standard formula | >68 |
+| NPS | Promoters - Detractors | >0 |
+
+---
+
+*See also: `journey-mapping-guide.md` for contextual research*

package/org-skills/verification-before-completion/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/org-skills/verification-before-completion/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: verification-before-completion
+description: "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always"
+tags: ["engineering","testing"]
+tools: []
+license: MIT
+source: https://github.com/obra/superpowers
+source_path: "skills/verification-before-completion"
+source_commit: 5bf4e78011075bcfc0dc295f0724994cd123ee71
+---
+# Verification Before Completion
+
+## Overview
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness

package/{dist/src/orgrt/role-skills/visionos-engineer.md → org-skills/visionos-engineer/SKILL.md}

@@ -1,3 +1,11 @@
+---
+name: visionos-engineer
+description: "visionOS Engineer role best practices. Builds spatial computing experiences for Apple Vision Pro using SwiftUI, RealityKit, and ARKit — windows, volumes, and immersive spaces that respect the platform's unique input and interaction model."
+tags: ["frontend","engineering"]
+tools: ["monograph_query","monograph_context","monograph_impact","monodesign_detect","monodesign_fix","monodesign_palette"]
+license: Apache-2.0
+source: https://github.com/monoes/monomind
+---
 # visionOS Engineer — Best Practices
 
 ## Focus

package/org-skills/visual-design-foundations/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Seth Hobson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.