@event4u/agent-config 5.10.0 → 6.0.0

package/.agent-src/skills/dashboard-design/SKILL.md

@@ -1,123 +0,0 @@
----
-model_tier: medium
-name: dashboard-design
-description: "Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling."
-domain: devops
-recommended_for_user_types: [ops, gtm]
-framework: laravel
-workspaces:
-  - engineering
-packs:
-  - engineering-base
----
-
-# dashboard-design
-
-## When to use
-
-Use when designing a new Grafana or admin dashboard, deciding what goes where (Grafana vs. app), or embedding Grafana panels in the Laravel app.
-
-Do NOT use when:
-- Writing Grafana queries/JSON (use `grafana` skill)
-- Building Livewire components (use `livewire` skill)
-
-## Procedure: Design a dashboard
-
-| Domain | Technology | Purpose |
-|---|---|---|
-| **Monitoring** | Grafana + Loki | Infrastructure health, error rates, logs, SLAs |
-| **Business/Admin** | Laravel + Livewire + Tailwind | Customer KPIs, import stats, usage metrics |
-
-### Decision: What goes where?
-
-| Data | Where |
-|---|---|
-| Server metrics, error rates, latency | Grafana |
-| Log analysis, traces | Grafana (Loki) |
-| SLA/uptime tracking | Grafana |
-| Customer-facing KPIs | App dashboard |
-| Import statistics per customer | App dashboard (+ Grafana embed) |
-| User activity, usage metrics | App dashboard |
-
-### Grafana Embedding
-
-```html
-<iframe
-  src="https://grafana.example.com/d-solo/{dashboard-uid}/{panel-id}?orgId=1&from=now-24h&to=now&var-fqdn={{ $customer->fqdn }}&theme=light"
-  width="100%" height="300" frameborder="0"
-></iframe>
-```
-
-Config required: `allow_embedding = true`, `cookie_samesite = none` (cross-origin), anonymous access/auth proxy, tenant variables via URL params, `&theme=light|dark`.
-
-| Scenario | Approach |
-|---|---|
-| Quick KPI overview | Embed Grafana stat panels |
-| Detailed investigation | Link to full Grafana dashboard |
-| Customer-facing | Build in app (full UX control) |
-
-## Admin Dashboard Design (Laravel)
-
-### Widget types
-
-| Widget | Implementation |
-|---|---|
-| Stat card | Livewire + Tailwind |
-| Trend card | Stat + sparkline (Chart.js / Grafana embed) |
-| Table widget | Livewire table with pagination |
-| Chart widget | Chart.js / Grafana embed |
-| Status list | Blade component with color indicators |
-| Activity feed | Livewire with polling/streaming |
-
-### Layout: F-pattern
-
-```
-┌──────────┬──────────┬──────────┬──────────┐
-│ Stat     │ Stat     │ Stat     │ Stat     │  ← KPI row
-├──────────┴──────────┼──────────┴──────────┤
-│ Chart (trend)       │ Chart (breakdown)   │  ← Viz row
-├─────────────────────┼─────────────────────┤
-│ Table (recent)      │ Activity feed       │  ← Detail row
-└─────────────────────┴─────────────────────┘
-```
-
-### Livewire patterns
-
-- `wire:poll.30s` for auto-refresh
-- `wire:init` for lazy loading expensive queries
-- `$dispatch('refresh-stats')` for cross-widget updates
-- Cache expensive aggregations, refresh on schedule
-
-### Validate
-
-- Verify each panel answers exactly one question.
-- Confirm time ranges are explicit, not "last X" without context.
-- Check that critical KPIs are visible without scrolling.
-- Ensure no chart mixes unrelated metrics on the same axis.
-
-## Output format
-
-1. Dashboard layout with panel placement and visualization types
-2. Data source mapping — which metrics/queries feed each panel
-3. Alerting thresholds where applicable
-
-## Gotcha
-
-- Max 8 panels per dashboard — cognitive overload kills usability.
-- Simple table often beats fancy visualization.
-- Always scope to customer/tenant — no unfiltered admin views.
-- Always define time range explicitly.
-
-## Do NOT
-
-- Do NOT create dashboards with more than 8 panels — cognitive overload.
-- Do NOT mix ops metrics with business KPIs on the same dashboard.
-- Do NOT show admin data without tenant scoping.
-
-## Auto-trigger keywords
-
-- dashboard
-- monitoring dashboard
-- visualization
-- KPI
-- metrics display

package/.agent-src/skills/database/SKILL.md

@@ -1,103 +0,0 @@
----
-model_tier: medium
-name: database
-description: "Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'."
-personas:
-  - eloquent-tamer
-domain: engineering
-workspaces:
-  - engineering
-packs:
-  - engineering-base
----
-
-# database
-
-## When to use
-
-Use when designing schemas, optimizing queries, adding indexes, or troubleshooting database performance.
-
-Do NOT use when:
-- Writing framework-specific ORM models (use the matching skill — e.g. `eloquent` for Laravel, `symfony-workflow` for Doctrine, framework-native skill for Prisma / TypeORM / SQLAlchemy / GORM / Diesel)
-- Creating migrations only — use the framework-specific migration skill (`laravel-migration` for Laravel, framework-native for others)
-
-## Procedure: Optimize a query
-
-### Step 0: Inspect
-
-1. Read project docs in `agents/reference/docs/` for database architecture.
-2. Check `config/database.php` for connection definitions.
-3. Detect engine: check `.env` driver and `docker-compose.yml`.
-
-### Step 1: Diagnose
-
-Run `EXPLAIN` / `EXPLAIN ANALYZE`:
-
-```sql
-EXPLAIN ANALYZE SELECT * FROM projects WHERE customer_id = 42 AND status = 'active';
-```
-
-Check for: full table scans (`type=ALL`), missing indexes (`key=NULL`), filesort, temporary tables.
-
-### Step 2: Fix
-
-- Add missing indexes (most selective column first in composites)
-- Rewrite anti-patterns (subquery → JOIN, `OFFSET` → cursor, `SELECT *` → specific columns)
-- Add eager loading for N+1 queries
-- Always paginate list endpoints
-
-### Step 3: Verify
-
-Re-run `EXPLAIN` and confirm improved plan.
-
-## Schema awareness (anti-hallucination)
-
-**Never guess table or column names.** Verify before writing queries/migrations:
-
-1. **Read migrations** — source of truth
-2. **Read models** — `$table`, `$connection`, `$fillable`, `$casts`, relationships
-3. **Run schema queries** — use the project's REPL or a raw introspection query:
-   - Laravel: `php artisan tinker --execute="Schema::getColumnListing('table')"`
-   - Symfony / Doctrine: `bin/console doctrine:mapping:info`
-   - Rails: `bin/rails runner "p ActiveRecord::Base.connection.columns('table').map(&:name)"`
-   - Prisma: `npx prisma db pull --print | grep -A20 "model Table"`
-   - Generic SQL: `psql -d mydb -c "\d table"` / `mysql -e "DESCRIBE table"`
-4. **Check project docs** — `agents/reference/docs/` for conventions
-
-| Trap | Reality |
-|---|---|
-| Assuming column exists | Check migration/model first |
-| Wrong table prefix | Customer tables may have prefixes |
-| Wrong connection | `api_database` vs `customer_database` — verify |
-| Inventing pivot tables | Check if they actually exist |
-
-## Conventions
-
-→ See guideline `php/database.md` for indexing, transactions, migrations, multi-connection patterns.
-
-## Output format
-
-1. Migration file or query change with EXPLAIN analysis
-2. Index recommendations with rationale
-
-## Gotcha
-
-- Check existing indexes before adding — duplicates waste write performance.
-- Consider multi-tenant implications — queries may need customer DB scoping.
-- `EXPLAIN` output varies between MariaDB and MySQL.
-- Don't use `TEXT` in WHERE without prefix index.
-
-## Do NOT
-
-- Do NOT guess table/column names — verify against migrations or models first.
-- Do NOT add indexes without checking existing ones — duplicates waste write performance.
-- Do NOT use `float` for money — use `decimal`.
-
-## Auto-trigger keywords
-
-- database
-- MariaDB
-- MySQL
-- migration
-- indexing
-- query optimization

package/.agent-src/skills/deep-reading-analyst/SKILL.md

@@ -1,198 +0,0 @@
----
-model_tier: high
-context: large
-name: deep-reading-analyst
-description: "Deep analysis of articles/long-form via thinking frameworks (SCQA, mental models, inversion) — 'analyze article', 'deep dive', 'extract insights', URL/text wanting depth not summary."
-status: active
-domain: discovery
-external_source: "https://github.com/ginobefun/deep-reading-analyst-skill/tree/26cd7dc9920e025d39751e396e707399022e49ef/src/deep-reading-analyst"
-refresh_trigger: "Upstream `ginobefun/deep-reading-analyst-skill` major rewrite (new framework added, dispatch table reshaped, or SHA pin invalidated by reference rename)."
-sunset_criterion: "Replace with a 50-line pointer skill if (a) all referenced modules are adopted as project-local guidelines (`docs/guidelines/agent-infra/{framework}.md`) AND (b) the dispatch logic moves into a project-native router."
-workspaces:
-  - engineering
-packs:
-  - engineering-base
----
-
-> **Pinned upstream:** `ginobefun/deep-reading-analyst-skill` @ SHA `26cd7dc9` (MIT). Re-verify per upstream major rewrite. Reference modules below link to the same SHA.
-
-# deep-reading-analyst
-
-Wing-1 deep-thinking skill for articles, papers, opinion pieces, case studies, and long-form decision documents. Routes the user's content through 8 thinking frameworks at four depth levels (Quick / Standard / Deep / Research) and returns insight tied to the user's **goal**, not framework completion.
-
-## When to use
-
-- User pastes an article URL, paper, or long text and wants depth ("analyze", "deep dive", "extract insights", "help me understand").
-- User asks for a specific framework ("apply SCQA to this", "use inversion thinking", "give me the mental models lens").
-- User is making a decision and wants pre-mortem / multi-lens analysis on a written proposal.
-- User is studying or note-taking on dense material (research papers, strategy memos, books).
-
-Do NOT use when:
-- User wants a 3-bullet TL;DR — use `agent-docs-writing` or write a direct summary.
-- Content is code or a diff — route to `judge-bug-hunter`, `judge-code-quality`, or `adversarial-review`.
-- User wants risk analysis on a code change — route to `adversarial-review` (diff-bound) or `threat-modeling`.
-- User wants debugging or incident analysis — route to `bug-analyzer` or `systematic-debugging`.
-
-## Framework Arsenal
-
-| Depth | Time | Frameworks | Reference module |
-|---|---|---|---|
-| **L1 — Quick** | ~15 min | SCQA, 5W2H | [`scqa-framework`](../../../docs/guidelines/agent-infra/scqa-framework.md), `5w2h_analysis.md` (upstream) |
-| **L2 — Standard** | ~30 min | L1 + Critical Thinking, Inversion | + [`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md), `critical_thinking.md` (upstream) |
-| **L3 — Deep** | ~60 min | L2 + Mental Models, First Principles, Systems Thinking, Six Hats | + [`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md), `first_principles.md`, `systems_thinking.md`, `six_hats.md` (upstream) |
-| **L4 — Research** | 120 min+ | L3 + Cross-source comparison via web search | + `comparison_matrix.md` (upstream) |
-
-Modules tagged `(upstream)` link to SHA-pinned files at the URL in `external_source` above; project-local modules are adopted as guidelines.
-
-## Procedure: deep-reading-analyst
-
-### Step 0: Inspect
-
-1. **Detect content type** — article, paper, opinion piece, case study, how-to, strategy memo. Drives auto-suggested frameworks (Step 1).
-2. **Detect goal signal** — problem-solving, learning, writing reference, decision-making, curiosity. Drives Step 4 output shape.
-3. **Skip if mismatched** — see "Do NOT use when" above; route to the named skill.
-
-### Step 1: Initialize Analysis
-
-Ask the user three things in **one** message (not three turns), per `ask-when-uncertain` Iron Law (one question per turn — these three are bundled into a single numbered-options block):
-
-1. **Goal** — problem-solving · learning · writing · decision-making · curiosity.
-2. **Depth** — L1 Quick (15 min) · L2 Standard (30 min) · L3 Deep (60 min) · L4 Research (120 min+).
-3. **Framework override** — defaults are auto-suggested by content type (table below); user may name specific frameworks.
-
-If the user does not answer, default to L2 Standard with auto-selected frameworks.
-
-**Auto-suggest matrix:**
-
-| Content type | Default frameworks |
-|---|---|
-| Strategy / business article | SCQA + Mental Models + Inversion |
-| Research paper | 5W2H + Critical Thinking + Systems Thinking |
-| How-to guide | SCQA + 5W2H + First Principles |
-| Opinion piece | Critical Thinking + Inversion + Six Hats |
-| Case study | SCQA + Mental Models + Systems Thinking |
-
-### Step 2: Structural Understanding (always run)
-
-Regardless of depth, open with two short blocks:
-
-**2A — Basic structure.**
-
-```markdown
-📄 Type: [article/paper/report]
-🎯 Core thesis: [one sentence]
-Structure:
-├─ Argument 1 → [key support]
-├─ Argument 2 → [key support]
-└─ Argument 3 → [key support]
-Key concepts: [3–5 terms with one-line definitions]
-```
-
-**2B — SCQA breakdown.** Apply the four-element decomposition from [`scqa-framework`](../../../docs/guidelines/agent-infra/scqa-framework.md):
-
-```markdown
-**S (Situation)**: [context the article establishes]
-**C (Complication)**: [problem identified]
-**Q (Question)**: [core question]
-**A (Answer)**: [main solution / conclusion]
-Structure quality — clarity / logic / completeness: [★★★☆☆]
-```
-
-**2C — 5W2H gap check** (L1+). Quick scan: which of *What, Why, Who, When, Where, How, How much* are well-covered, partial, or missing? Flag the 1–2 most critical gaps.
-
-### Step 3: Apply Frameworks (depth-gated)
-
-Load only the frameworks the user's depth bought. Each framework follows the same pattern: **load reference module → apply lens → produce one fixed-shape block**.
-
-**L2 additions:**
-
-- **Critical Thinking** (`critical_thinking.md`, upstream) — argument strength score (X/10), strengths, weaknesses, logical fallacies detected.
-- **Inversion** ([`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md)) — pre-mortem on the article's recommendation: "how would this fail?", missing risk factors, mitigations.
-
-**L3 additions:**
-
-- **Mental Models** ([`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md)) — pick 3–5 models from different disciplines (physics, biology, psychology, economics, math), apply each lens, surface cross-model patterns.
-- **First Principles** (`first_principles.md`, upstream) — strip to fundamental truths, validate each core assumption, rebuild from base.
-- **Systems Thinking** (`systems_thinking.md`, upstream) — map relationships, feedback loops, leverage points.
-- **Six Hats** (`six_hats.md`, upstream) — White (facts), Red (feelings), Black (cautions), Yellow (benefits), Green (creativity), Blue (process).
-
-**L4 addition:**
-
-- **Cross-source comparison** (`comparison_matrix.md`, upstream) — web-search 2–3 related sources, compare SCQA across sources, identify consensus vs divergence, synthesize integrated perspective.
-
-### Step 4: Synthesize by Goal
-
-Output shape is **driven by Step 0 goal**, not by frameworks applied. Pick exactly one of the four blocks below.
-
-**For problem-solving:** Applicable solutions (2–3 from content) → Application plan with timed action steps → Success metrics → Risk mitigations from Inversion.
-
-**For learning:** Core concepts (definition + example) → Mental models gained → Connections to prior knowledge → First Principles fundamental question → 3 verification questions (understanding / application / evaluation).
-
-**For writing reference:** Key arguments + evidence (with paragraph citations) → Quotable insights with context → Critical analysis (strengths for citing, limitations for balanced discussion) → Alternative perspectives from Mental Models → Gaps and counterfactuals.
-
-**For decision-making:** Options presented → Multi-model evaluation (economic + risk + systems lens) → Six Hats decision analysis → Scenario analysis (best / worst / most likely) → Synthesized recommendation.
-
-### Step 5: Knowledge Activation (always end here)
-
-Regardless of goal, close with three fixed blocks:
-
-```markdown
-## 🎯 Top 3 takeaways
-1. **[Insight]** — Why it matters: [...] · One action: [specific, time-bound]
-2. **[Insight]** — Why it matters: [...] · One action: [specific, time-bound]
-3. **[Insight]** — Why it matters: [...] · One action: [specific, time-bound]
-
-## 💡 Quick win — one tiny, specific action for the next 24 hours.
-
-## 🧭 Frameworks used
-✅ SCQA  ✅ 5W2H  ✅ Critical  ✅ Inversion
-□ Mental Models  □ First Principles  □ Systems  □ Six Hats
-```
-
-### Step 6: Validate
-
-1. Every claim is faithful to the source — no misrepresentation, facts distinguished from opinions.
-2. Frameworks applied **purposefully**, not force-fit — drop a framework that adds no insight rather than padding the output.
-3. Output ends with concrete, actionable steps — no analysis-without-application.
-4. Specific citations (paragraph numbers, quotes) where the source supports them.
-
-## Output format
-
-1. **Structural block (Step 2)** — type / thesis / structure tree / key concepts / SCQA / 5W2H gaps.
-2. **Framework blocks (Step 3)** — one fixed-shape block per framework the depth bought.
-3. **Goal-shaped synthesis (Step 4)** — problem-solving / learning / writing / decision-making.
-4. **Knowledge activation (Step 5)** — top 3 takeaways · quick win · frameworks-used checkboxes.
-
-## Gotcha
-
-- The model tends to **apply every framework** even at L1 — respect the depth budget; skip frameworks the user did not buy.
-- The model tends to **summarize** instead of analyze when the user pastes long text — go deep on 1–3 points, not shallow on all of them.
-- Inversion drifts into adversarial code review — this skill targets **decisions and arguments**, not diffs. Route diff stress-tests to `adversarial-review` / `judge-bug-hunter`.
-- Mental Models drifts into name-dropping — pick 3–5, apply each lens *concretely* to the article's claims, drop models that yield no new insight.
-- L4 cross-source comparison drifts into a literature review — keep it to 2–3 sources, focus on consensus / divergence / unique value.
-- Output without action steps is a failure mode — every Step-4 synthesis must end with timed, concrete actions tied to the user's goal.
-
-## Do NOT
-
-- Do NOT force-apply all frameworks at the user's chosen depth — drop ones that add no insight.
-- Do NOT copy text verbatim from the source — always reword for the user's understanding.
-- Do NOT use academic jargon without one-line definitions in the "key concepts" block.
-- Do NOT skip Step 5 — the takeaways + quick win are the load-bearing output, not optional decoration.
-- Do NOT route code reviews, diff stress-tests, or incident debugging through this skill.
-
-## Reference modules
-
-Project-local guidelines (full text adopted under the Reference-Guideline Sunset Policy):
-
-- [`scqa-framework`](../../../docs/guidelines/agent-infra/scqa-framework.md) — full 499-line authoritative-link adopt.
-- [`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md) — pure adopt of Munger's multi-discipline toolkit.
-- [`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md) — pre-mortem on decisions, distinct from `adversarial-review`.
-
-Upstream modules (loaded on demand from the SHA-pinned URL in `external_source`):
-
-- `5w2h_analysis.md` — completeness check (7 questions).
-- `critical_thinking.md` — argument quality / fallacy detection.
-- `first_principles.md` — fundamental-truth extraction.
-- `systems_thinking.md` — feedback loops + leverage points.
-- `six_hats.md` — White / Red / Black / Yellow / Green / Blue protocol.
-- `comparison_matrix.md` — cross-source synthesis (L4 only).

package/.agent-src/skills/design-review/SKILL.md

@@ -1,233 +0,0 @@
----
-model_tier: high
-name: design-review
-description: "Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more."
-domain: quality
-workspaces:
-  - engineering
-packs:
-  - engineering-base
----
-
-# design-review
-
-## When to use
-
-Use this skill when:
-- Reviewing pull requests with UI changes
-- Auditing frontend components for design quality
-- Verifying responsive design across viewports
-- Checking accessibility compliance (WCAG 2.1 AA)
-- Testing interaction flows and user experience
-- Conducting visual QA on new features
-
-Do NOT use when:
-- Creating new designs (use `fe-design` skill instead)
-- Reviewing backend/API code only
-- Quick syntax checks (use linters)
-
-## Prerequisites
-
-One of the following browser automation tools:
-- **Playwright MCP** (recommended) — browser automation, screenshots, viewport testing
-- **Chrome DevTools** — screenshot capture, performance analysis
-
-A **live preview URL** is required for testing.
-
-## Procedure: Design review
-
-### Phase 0: Preparation
-
-- Read PR description and git diff.
-- Identify changed components and affected pages.
-- Navigate to preview URL.
-- Take baseline screenshot.
-
-### Phase 1: Interaction
-
-- Test user flows end-to-end.
-- Verify hover, focus, active, and disabled states.
-- Test keyboard navigation (Tab, Enter, Escape, Arrow keys).
-- Check loading states and transitions.
-- Verify form submission and error recovery.
-
-### Phase 2: Responsiveness
-
-Test at three viewports:
-
-| Viewport | Width | Device |
-|---|---|---|
-| Desktop | 1440px | Standard monitor |
-| Tablet | 768px | iPad |
-| Mobile | 375px | iPhone SE |
-
-- Take screenshots at each viewport.
-- Check layout shifts, overflow, and content reflow.
-- Verify touch targets are at least 44x44px on mobile.
-
-### Phase 3: Visual Polish
-
-- **Typography:** Font sizes, weights, line heights, hierarchy.
-- **Spacing:** Consistent margins, padding, alignment.
-- **Colors:** Contrast ratios, brand consistency, dark mode.
-- **Alignment:** Grid alignment, visual balance.
-- **Icons:** Consistent size, style, and spacing.
-
-### Phase 4: Accessibility (WCAG 2.1 AA)
-
-| Criterion | Check |
-|---|---|
-| **1.1.1** | All images have meaningful alt text |
-| **1.3.1** | Semantic HTML (headings, landmarks, lists) |
-| **1.4.3** | Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text) |
-| **1.4.11** | Non-text contrast ≥ 3:1 (UI components, borders) |
-| **2.1.1** | All functionality available via keyboard |
-| **2.4.3** | Focus order is logical and predictable |
-| **2.4.7** | Focus indicator is visible |
-| **3.3.1** | Error messages identify the field and describe the error |
-| **3.3.2** | Labels and instructions for form inputs |
-| **4.1.2** | ARIA roles, states, and properties are correct |
-
-### Phase 5: Robustness
-
-- **Empty states:** What happens with no data?
-- **Error states:** What happens when things fail?
-- **Content overflow:** Long text, many items, large numbers.
-- **Loading states:** Skeleton screens, spinners, progressive loading.
-- **Boundary values:** Min/max inputs, special characters.
-
-### Phase 6: Code Health
-
-- Component reuse — are existing components used where possible?
-- Design tokens — are colors, spacing, fonts from the design system?
-- CSS patterns — utility classes vs. custom CSS, consistency.
-- Accessibility in code — semantic HTML, ARIA attributes.
-
-### Phase 7: Content & Console
-
-- Grammar and spelling in UI text.
-- Consistent terminology and tone.
-- No placeholder text left in production.
-- Check browser console for JavaScript errors or warnings.
-
-## Communication principles
-
-### Problems over prescriptions
-
-Describe **what's wrong and why it matters**, not how to fix it.
-
-```
-❌ "Change margin to 16px"
-✅ "Spacing feels inconsistent with adjacent elements, creating visual clutter near the CTA."
-```
-
-### Triage matrix
-
-Every issue gets a severity:
-
-| Severity | Meaning | Action |
-|---|---|---|
-| **Blocker** | Must fix before merge | Blocks PR |
-| **High** | Should fix before merge | Strong recommendation |
-| **Medium** | Consider for follow-up | Suggestion |
-| **Nitpick** | Optional polish | Prefix with "Nit:" |
-
-### Evidence-based
-
-Screenshots required for all visual issues. Reference specific viewport and state.
-
-### Start positive
-
-Acknowledge what works well before listing issues.
-
-## Report structure
-
-```markdown
-## Design Review Summary
-[Positive opening + overall assessment]
-
-### 🚫 Blockers
-[Critical issues — must fix]
-
-### ⚠️ High Priority
-[Significant issues — should fix]
-
-### 💡 Suggestions
-[Improvements for follow-up]
-
-### ✨ Nitpicks
-[Minor aesthetic details]
-
-### Testing Evidence
-[Screenshots: Desktop, Tablet, Mobile]
-
-### Next Steps
-1. [Fix blockers]
-2. [Address high-priority]
-
-**Overall: [Ready to merge | Needs revisions]**
-```
-
-
-## Visual QA with browser automation
-
-When Playwright MCP or browser tools are available, use them for automated visual verification:
-
-### Before/After comparison
-
-1. **Capture baseline** — screenshot before changes at all 3 viewports.
-2. **Apply changes** — deploy or hot-reload.
-3. **Capture after** — screenshot at the same viewports and states.
-4. **Compare** — visually diff the screenshots, flag regressions.
-
-### State-based verification
-
-Don't just screenshot the default state. Capture:
-
-| State | How to trigger |
-|---|---|
-| Empty | Remove data, check empty state UI |
-| Loading | Throttle network, capture skeleton/spinner |
-| Error | Force an error response, check error UI |
-| Overflow | Add very long text, many items |
-| Interactive | Hover, focus, open dropdowns |
-
-### Mockup-to-code verification
-
-When implementing from a design mockup or screenshot:
-
-1. **Open the mockup** — use the provided image/screenshot.
-2. **Implement** — build the UI component.
-3. **Side-by-side** — compare mockup vs. implementation at the same viewport.
-4. **Flag deviations** — spacing, colors, typography, alignment differences.
-
-This is especially useful when the user provides a screenshot or Figma export as a reference.
-
-## Output format
-
-1. Design review report following the Report structure section
-2. Severity-rated findings (blocker, suggestion, nit)
-3. Accessibility and responsive compliance summary
-
-## Auto-trigger keywords
-
-- design review
-- UI review
-- UX audit
-- accessibility
-- WCAG
-- responsive
-
-## Gotcha
-
-- Don't review design without understanding the user's constraints (time, resources, scope).
-- The model tends to suggest accessibility improvements that break the existing design system.
-- "Best practice" is not always the right choice — sometimes "good enough" ships faster.
-
-## Do NOT
-
-- Do NOT skip accessibility testing — it's not optional.
-- Do NOT report issues without evidence (screenshots, specific elements).
-- Do NOT prescribe solutions — describe problems and impact.
-- Do NOT block PRs on nitpicks.
-- Do NOT test only at desktop resolution.