@bastani/atomic 0.5.11 → 0.5.12-1

package/.agents/skills/create-spec/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: create-spec
+description: Create a detailed execution plan for implementing features or refactors in a codebase by leveraging existing research in the specified `research` directory.
+---
+
+You are tasked with creating a spec for implementing a new feature or system change in the codebase by leveraging existing research in the **$ARGUMENTS** path. If no research path is specified, use the entire `research/` directory. IMPORTANT: Research documents are located in the `research/` directory — do NOT look in the `specs/` directory for research. Follow the template below to produce a comprehensive specification as output in the `specs/` folder using the findings from RELEVANT research documents found in `research/`. The spec file MUST be named using the format `YYYY-MM-DD-topic.md` (e.g., `specs/2026-03-26-my-feature.md`), where the date is the current date and the topic is a kebab-case summary. Tip: It's good practice to use the `codebase-research-locator` and `codebase-research-analyzer` agents to help you find and analyze the research documents in the `research/` directory. It is also HIGHLY recommended to cite relevant research throughout the spec for additional context.
+
+<EXTREMELY_IMPORTANT>
+
+- Please DO NOT implement anything in this stage, just create the comprehensive spec as described below.
+- When writing the spec, DO NOT include information about concrete dates/timelines (e.g. # minutes, hours, days, weeks, etc.) and favor explicit phases (e.g. Phase 1, Phase 2, etc.).
+- Once the spec is generated, refer to the section, "## 9. Open Questions / Unresolved Issues", go through each question one by one, and use **contrastive clarification** (presenting 2-3 specific options with concrete tradeoffs) rather than open-ended questions. This means presenting interpretations like "(A) Option X — tradeoff Y" and "(B) Option Z — tradeoff W" instead of asking "what do you think about X?". Update the spec with the user's answers as you walk through the questions.
+    - Please use your AskUserQuestion tool to ask the user for their input on each question and update the spec accordingly.
+- Finally, once the spec is generated and after open questions are answered, provide an executive summary of the spec to the user including the path to the generated spec document in the `specs/` directory.
+    - Encourage the user to review the spec for best results and provide feedback or ask any follow-up questions they may have.
+
+</EXTREMELY_IMPORTANT>
+
+# [Project Name] Technical Design Document / RFC
+
+| Document Metadata      | Details                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| Author(s)              | !`git config user.name`                                                        |
+| Status                 | Draft (WIP) / In Review (RFC) / Approved / Implemented / Deprecated / Rejected |
+| Team / Owner           |                                                                                |
+| Created / Last Updated |                                                                                |
+
+## 1. Executive Summary
+
+_Instruction: A "TL;DR" of the document. Assume the reader is a VP or an engineer from another team who has 2 minutes. Summarize the Context (Problem), the Solution (Proposal), and the Impact (Value). Keep it under 200 words._
+
+> **Example:** This RFC proposes replacing our current nightly batch billing system with an event-driven architecture using Kafka and AWS Lambda. Currently, billing delays cause a 5% increase in customer support tickets. The proposed solution will enable real-time invoicing, reducing billing latency from 24 hours to <5 minutes.
+
+## 2. Context and Motivation
+
+_Instruction: Why are we doing this? Why now? Link to the Product Requirement Document (PRD)._
+
+### 2.1 Current State
+
+_Instruction: Describe the existing architecture. Use a "Context Diagram" if possible. Be honest about the flaws._
+
+- **Architecture:** Currently, Service A communicates with Service B via a shared SQL database.
+- **Limitations:** This creates a tight coupling; when Service A locks the table, Service B times out.
+
+### 2.2 The Problem
+
+_Instruction: What is the specific pain point?_
+
+- **User Impact:** Customers cannot download receipts during the nightly batch window.
+- **Business Impact:** We are losing $X/month in churn due to billing errors.
+- **Technical Debt:** The current codebase is untestable and has 0% unit test coverage.
+
+## 3. Goals and Non-Goals
+
+_Instruction: This is the contract Definition of Success. Be precise._
+
+### 3.1 Functional Goals
+
+- [ ] Users must be able to export data in CSV format.
+- [ ] System must support multi-tenant data isolation.
+
+### 3.2 Non-Goals (Out of Scope)
+
+_Instruction: Explicitly state what you are NOT doing. This prevents scope creep._
+
+- [ ] We will NOT support PDF export in this version (CSV only).
+- [ ] We will NOT migrate data older than 3 years.
+- [ ] We will NOT build a custom UI (API only).
+
+## 4. Proposed Solution (High-Level Design)
+
+_Instruction: The "Big Picture." Diagrams are mandatory here._
+
+### 4.1 System Architecture Diagram
+
+_Instruction: Insert a C4 System Context or Container diagram. Show the "Black Boxes."_
+
+- (Place Diagram Here - e.g., Mermaid diagram)
+
+For example,
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef','background':'#f5f7fa','mainBkg':'#f8f9fa','nodeBorder':'#4a5568','clusterBkg':'#ffffff','clusterBorder':'#cbd5e0','edgeLabelBackground':'#ffffff'}}}%%
+
+flowchart TB
+    %% ---------------------------------------------------------
+    %% CLEAN ENTERPRISE DESIGN
+    %% Professional • Trustworthy • Corporate Standards
+    %% ---------------------------------------------------------
+
+    %% STYLE DEFINITIONS
+    classDef person fill:#5a67d8,stroke:#4c51bf,stroke-width:3px,color:#ffffff,font-weight:600,font-size:14px
+
+    classDef systemCore fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:14px
+
+    classDef systemSupport fill:#667eea,stroke:#5a67d8,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+
+    classDef database fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+
+    classDef external fill:#718096,stroke:#4a5568,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px,stroke-dasharray:6 3
+
+    %% NODES - CLEAN ENTERPRISE HIERARCHY
+
+    User(("◉<br><b>User</b><br>")):::person
+
+    subgraph SystemBoundary["◆ Primary System Boundary"]
+        direction TB
+
+        LoadBalancer{{"<b>Load Balancer</b><br>NGINX<br><i>Layer 7 Proxy</i>"}}:::systemCore
+
+        API["<b>API Application</b><br>Go • Gin Framework<br><i>REST Endpoints</i>"]:::systemCore
+
+        Worker(["<b>Background Worker</b><br>Go Runtime<br><i>Async Processing</i>"]):::systemSupport
+
+        Cache[("◆<br><b>Cache Layer</b><br>Redis<br><i>In-Memory</i>")]:::database
+
+        PrimaryDB[("●<br><b>Primary Database</b><br>PostgreSQL<br><i>Persistent Storage</i>")]:::database
+    end
+
+    ExternalAPI{{"<b>External API</b><br>Third Party<br><i>HTTP/REST</i>"}}:::external
+
+    %% RELATIONSHIPS - CLEAN FLOW
+
+    User -->|"1. HTTPS Request<br>TLS 1.3"| LoadBalancer
+    LoadBalancer -->|"2. Proxy Pass<br>Round Robin"| API
+
+    API <-->|"3. Cache<br>Read/Write"| Cache
+    API -->|"4. Persist Data<br>Transactional"| PrimaryDB
+    API -.->|"5. Enqueue Event<br>Async"| Worker
+
+    Worker -->|"6. Process Job<br>Execution"| PrimaryDB
+    Worker -.->|"7. HTTP Call<br>Webhooks"| ExternalAPI
+
+    %% STYLE BOUNDARY
+    style SystemBoundary fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4,font-weight:600,font-size:12px
+```
+
+### 4.2 Architectural Pattern
+
+_Instruction: Name the pattern (e.g., "Event Sourcing", "BFF - Backend for Frontend")._
+
+- We are adopting a Publisher-Subscriber pattern where the Order Service publishes `OrderCreated` events, and the Billing Service consumes them asynchronously.
+
+### 4.3 Key Components
+
+| Component         | Responsibility              | Technology Stack  | Justification                                |
+| ----------------- | --------------------------- | ----------------- | -------------------------------------------- |
+| Ingestion Service | Validates incoming webhooks | Go, Gin Framework | High concurrency performance needed.         |
+| Event Bus         | Decouples services          | Kafka             | Durable log, replay capability.              |
+| Projections DB    | Read-optimized views        | MongoDB           | Flexible schema for diverse receipt formats. |
+
+## 5. Detailed Design
+
+_Instruction: The "Meat" of the document. Sufficient detail for an engineer to start coding._
+
+### 5.1 API Interfaces
+
+_Instruction: Define the contract. Use OpenAPI/Swagger snippets or Protocol Buffer definitions._
+
+**Endpoint:** `POST /api/v1/invoices`
+
+- **Auth:** Bearer Token (Scope: `invoice:write`)
+- **Idempotency:** Required header `X-Idempotency-Key`
+- **Request Body:**
+
+```json
+{ "user_id": "uuid", "amount": 100.0, "currency": "USD" }
+```
+
+### 5.2 Data Model / Schema
+
+_Instruction: Provide ERDs (Entity Relationship Diagrams) or JSON schemas. Discuss normalization vs. denormalization._
+
+**Table:** `invoices` (PostgreSQL)
+
+| Column    | Type | Constraints       | Description           |
+| --------- | ---- | ----------------- | --------------------- |
+| `id`      | UUID | PK                |                       |
+| `user_id` | UUID | FK -> Users       | Partition Key         |
+| `status`  | ENUM | 'PENDING', 'PAID' | Indexed for filtering |
+
+### 5.3 Algorithms and State Management
+
+_Instruction: Describe complex logic, state machines, or consistency models._
+
+- **State Machine:** An invoice moves from `DRAFT` -> `LOCKED` -> `PROCESSING` -> `PAID`.
+- **Concurrency:** We use Optimistic Locking on the `version` column to prevent double-payments.
+
+## 6. Alternatives Considered
+
+_Instruction: Prove you thought about trade-offs. Why is your solution better than the others?_
+
+| Option                           | Pros                               | Cons                                      | Reason for Rejection                                                          |
+| -------------------------------- | ---------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
+| Option A: Synchronous HTTP Calls | Simple to implement, Easy to debug | Tight coupling, cascading failures        | Latency requirements (200ms) make blocking calls risky.                       |
+| Option B: RabbitMQ               | Lightweight, Built-in routing      | Less durable than Kafka, harder to replay | We need message replay for auditing (Compliance requirement).                 |
+| Option C: Kafka (Selected)       | High throughput, Replayability     | Operational complexity                    | **Selected:** The need for auditability/replay outweighs the complexity cost. |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **Authentication:** Services authenticate via mTLS.
+- **Authorization:** Policy enforcement point at the API Gateway (OPA - Open Policy Agent).
+- **Data Protection:** PII (Names, Emails) is encrypted at rest using AES-256.
+- **Threat Model:** Primary threat is compromised API Key; remediation is rapid rotation and rate limiting.
+
+### 7.2 Observability Strategy
+
+- **Metrics:** We will track `invoice_creation_latency` (Histogram) and `payment_failure_count` (Counter).
+- **Tracing:** All services propagate `X-Trace-ID` headers (OpenTelemetry).
+- **Alerting:** PagerDuty triggers if `5xx` error rate > 1% for 5 minutes.
+
+### 7.3 Scalability and Capacity Planning
+
+- **Traffic Estimates:** 1M transactions/day = ~12 TPS avg / 100 TPS peak.
+- **Storage Growth:** 1KB per record \* 1M = 1GB/day.
+- **Bottleneck:** The PostgreSQL Write node is the bottleneck. We will implement Read Replicas to offload traffic.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] Phase 1: Deploy services in "Shadow Mode" (process traffic but do not email users).
+- [ ] Phase 2: Enable Feature Flag `new-billing-engine` for 1% of internal users.
+- [ ] Phase 3: Ramp to 100%.
+
+### 8.2 Data Migration Plan
+
+- **Backfill:** We will run a script to migrate the last 90 days of invoices from the legacy SQL server.
+- **Verification:** A "Reconciliation Job" will run nightly to compare Legacy vs. New totals.
+
+### 8.3 Test Plan
+
+- **Unit Tests:**
+- **Integration Tests:**
+- **End-to-End Tests:**
+
+## 9. Open Questions / Unresolved Issues
+
+_Instruction: List known unknowns. These must be resolved before the doc is marked "Approved"._
+
+- [ ] Will the Legal team approve the 3rd party library for PDF generation?
+- [ ] Does the current VPC peering allow connection to the legacy mainframe?

package/.agents/skills/critique/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: critique
+description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, automated anti-pattern detection, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component.
+version: 2.1.1
+user-invocable: true
+argument-hint: "[area (feature, page, component...)]"
+---
+
+## STEPS
+
+### Step 1: Preparation
+
+Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what the interface is trying to accomplish.
+
+### Step 2: Gather Assessments
+
+Launch two independent assessments. **Neither must see the other's output** to avoid bias.
+
+You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet.
+
+If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding.
+
+**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state.
+
+#### Assessment A: LLM Design Review
+
+Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title:
+```javascript
+document.title = '[LLM] ' + document.title;
+```
+Think like a design director. Evaluate:
+
+**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately?
+
+**Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness).
+
+**Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)):
+- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical.
+- Count visible options at each decision point. If >4, flag it.
+- Check for progressive disclosure: is complexity revealed only when needed?
+
+**Emotional Journey**:
+- What emotion does this interface evoke? Is that intentional?
+- **Peak-end rule**: Is the most intense moment positive? Does the experience end well?
+- **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)?
+
+**Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)):
+Score each of the 10 heuristics 0-4. This scoring will be presented in the report.
+
+Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions.
+
+#### Assessment B: Automated Detection
+
+Run the bundled deterministic detector, which flags 25 specific patterns (AI slop tells + general design quality).
+
+**CLI scan**:
+```bash
+npx impeccable --json [--fast] [target]
+```
+
+- Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files.
+- For URLs, skip the CLI scan (it requires Puppeteer). Use browser visualization instead.
+- For large directories (200+ scannable files), use `--fast` (regex-only, skips jsdom)
+- For 500+ files, narrow scope or ask the user
+- Exit code 0 = clean, 2 = findings
+
+**Browser visualization** (when browser automation tools are available AND the target is a viewable page):
+
+The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically.
+
+1. **Start the live detection server**:
+   ```bash
+   npx impeccable live &
+   ```
+   Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it.
+2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs.
+3. **Label the tab** via `javascript_tool` so the user can distinguish it:
+   ```javascript
+   document.title = '[Human] ' + document.title;
+   ```
+4. **Scroll to top** to ensure the page is scrolled to the very top before injection
+5. **Inject** via `javascript_tool` (replace PORT with the port from step 1):
+   ```javascript
+   const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s);
+   ```
+6. Wait 2-3 seconds for the detector to render overlays
+7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays.
+8. **Cleanup**: Stop the live server when done:
+   ```bash
+   npx impeccable live stop
+   ```
+
+For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only.
+
+Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted.
+
+### Step 3: Generate Combined Critique Report
+
+Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives.
+
+Structure your feedback as a design director would:
+
+#### Design Health Score
+> *Consult [heuristics-scoring](reference/heuristics-scoring.md)*
+
+Present the Nielsen's 10 heuristics scores as a table:
+
+| # | Heuristic | Score | Key Issue |
+|---|-----------|-------|-----------|
+| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] |
+| 2 | Match System / Real World | ? | |
+| 3 | User Control and Freedom | ? | |
+| 4 | Consistency and Standards | ? | |
+| 5 | Error Prevention | ? | |
+| 6 | Recognition Rather Than Recall | ? | |
+| 7 | Flexibility and Efficiency | ? | |
+| 8 | Aesthetic and Minimalist Design | ? | |
+| 9 | Error Recovery | ? | |
+| 10 | Help and Documentation | ? | |
+| **Total** | | **??/40** | **[Rating band]** |
+
+Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32.
+
+#### Anti-Patterns Verdict
+
+**Start here.** Does this look AI-generated?
+
+**LLM assessment**: Your own evaluation of AI slop tells. Cover overall aesthetic feel, layout sameness, generic composition, missed opportunities for personality.
+
+**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. Note any additional issues the detector caught that you missed, and flag any false positives.
+
+**Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported.
+
+#### Overall Impression
+A brief gut reaction: what works, what doesn't, and the single biggest opportunity.
+
+#### What's Working
+Highlight 2-3 things done well. Be specific about why they work.
+
+#### Priority Issues
+The 3-5 most impactful design problems, ordered by importance.
+
+For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions):
+- **[P?] What**: Name the problem clearly
+- **Why it matters**: How this hurts users or undermines goals
+- **Fix**: What to do about it (be concrete)
+- **Suggested command**: Which command could address this (from: /animate, /quieter, /shape, /optimize, /adapt, /clarify, /layout, /distill, /delight, /audit, /harden, /polish, /bolder, /typeset, /critique, /colorize, /overdrive)
+
+#### Persona Red Flags
+> *Consult [personas](reference/personas.md)*
+
+Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `.github/copilot-instructions.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info.
+
+For each selected persona, walk through the primary user action and list specific red flags found:
+
+**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. High abandonment risk.
+
+**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2.
+
+Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them.
+
+#### Minor Observations
+Quick notes on smaller issues worth addressing.
+
+#### Questions to Consider
+Provocative questions that might unlock better solutions:
+- "What if the primary action were more prominent?"
+- "Does this need to feel this complex?"
+- "What would a confident version of this look like?"
+
+**Remember**:
+- Be direct. Vague feedback wastes everyone's time.
+- Be specific. "The submit button," not "some elements."
+- Say what's wrong AND why it matters to users.
+- Give concrete suggestions, not just "consider exploring..."
+- Prioritize ruthlessly. If everything is important, nothing is.
+- Don't soften criticism. Developers need honest feedback to ship great design.
+
+### Step 4: Ask the User
+
+**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan.
+
+Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions):
+
+1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options.
+
+2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found.
+
+3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only".
+
+4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done.
+
+**Rules for questions**:
+- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions.
+- Keep it to 2-4 questions maximum. Respect the user's time.
+- Offer concrete options, not open-ended prompts.
+- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5.
+
+### Step 5: Recommended Actions
+
+**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Step 4.
+
+#### Action Summary
+
+List recommended commands in priority order, based on the user's answers:
+
+1. **`/command-name`**: Brief description of what to fix (specific context from critique findings)
+2. **`/command-name`**: Brief description (specific context)
+...
+
+**Rules for recommendations**:
+- Only recommend commands from: /animate, /quieter, /shape, /optimize, /adapt, /clarify, /layout, /distill, /delight, /audit, /harden, /polish, /bolder, /typeset, /critique, /colorize, /overdrive
+- Order by the user's stated priorities first, then by impact
+- Each item's description should carry enough context that the command knows what to focus on
+- Map each Priority Issue to the appropriate command
+- Skip commands that would address zero issues
+- If the user chose a limited scope, only include items within that scope
+- If the user marked areas as off-limits, exclude commands that would touch those areas
+- End with `/polish` as the final step if any fixes were recommended
+
+After presenting the summary, tell the user:
+
+> You can ask me to run these one at a time, all at once, or in any order you prefer.
+>
+> Re-run `/critique` after fixes to see your score improve.

package/.agents/skills/critique/reference/cognitive-load.md

@@ -0,0 +1,106 @@
+# Cognitive Load Assessment
+
+Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload.
+
+---
+
+## Three Types of Cognitive Load
+
+### Intrinsic Load — The Task Itself
+Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it.
+
+**Manage it by**:
+- Breaking complex tasks into discrete steps
+- Providing scaffolding (templates, defaults, examples)
+- Progressive disclosure — show what's needed now, hide the rest
+- Grouping related decisions together
+
+### Extraneous Load — Bad Design
+Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste.
+
+**Common sources**:
+- Confusing navigation that requires mental mapping
+- Unclear labels that force users to guess meaning
+- Visual clutter competing for attention
+- Inconsistent patterns that prevent learning
+- Unnecessary steps between user intent and result
+
+### Germane Load — Learning Effort
+Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery.
+
+**Support it by**:
+- Progressive disclosure that reveals complexity gradually
+- Consistent patterns that reward learning
+- Feedback that confirms correct understanding
+- Onboarding that teaches through action, not walls of text
+
+---
+
+## Cognitive Load Checklist
+
+Evaluate the interface against these 8 items:
+
+- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements?
+- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)?
+- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)?
+- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen?
+- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next?
+- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)?
+- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one?
+- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it?
+
+**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed).
+
+---
+
+## The Working Memory Rule
+
+**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001).
+
+At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider:
+- **≤4 items**: Within working memory limits — manageable
+- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure
+- **8+ items**: Overloaded — users will skip, misclick, or abandon
+
+**Practical applications**:
+- Navigation menus: ≤5 top-level items (group the rest under clear categories)
+- Form sections: ≤4 fields visible per group before a visual break
+- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu
+- Dashboard widgets: ≤4 key metrics visible without scrolling
+- Pricing tiers: ≤3 options (more causes analysis paralysis)
+
+---
+
+## Common Cognitive Load Violations
+
+### 1. The Wall of Options
+**Problem**: Presenting 10+ choices at once with no hierarchy.
+**Fix**: Group into categories, highlight recommended, use progressive disclosure.
+
+### 2. The Memory Bridge
+**Problem**: User must remember info from step 1 to complete step 3.
+**Fix**: Keep relevant context visible, or repeat it where it's needed.
+
+### 3. The Hidden Navigation
+**Problem**: User must build a mental map of where things are.
+**Fix**: Always show current location (breadcrumbs, active states, progress indicators).
+
+### 4. The Jargon Barrier
+**Problem**: Technical or domain language forces translation effort.
+**Fix**: Use plain language. If domain terms are unavoidable, define them inline.
+
+### 5. The Visual Noise Floor
+**Problem**: Every element has the same visual weight — nothing stands out.
+**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted.
+
+### 6. The Inconsistent Pattern
+**Problem**: Similar actions work differently in different places.
+**Fix**: Standardize interaction patterns. Same type of action = same type of UI.
+
+### 7. The Multi-Task Demand
+**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating).
+**Fix**: Sequence the steps. Let the user do one thing at a time.
+
+### 8. The Context Switch
+**Problem**: User must jump between screens/tabs/modals to gather info for a single decision.
+**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth.