@event4u/agent-config 5.10.1 → 6.0.0

package/dist/agent-src/skills/corpus-grounding/scripts/schema_validator.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""corpus-grounding · schema_validator — manifest contract (interface v1).
+
+Validates a domain's plug-in manifest (`manifest.json`) against the
+schema-agnostic contract from ADR-061 §3. Each domain declares its OWN
+axes — the validator checks structure + provenance discipline, never a
+uniform schema.
+
+Pure stdlib, no network. Interface contract: SKILL.md § Interface contract.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+MANIFEST_VERSION = 1
+
+#: Output sophistication tiers (ADR-061 §3).
+TIERS = ("lookup-only", "conditional-grounding", "constraint-emission")
+
+_REQUIRED_TOP = ("manifest_version", "domain", "tier", "domains")
+_REQUIRED_PROVENANCE = ("owner", "refresh_cadence", "upstream")
+_REQUIRED_DOMAIN_KEYS = ("file", "search_cols", "output_cols")
+_REQUIRED_REASONING_KEYS = ("file", "match_column", "plan")
+
+
+class ManifestError(ValueError):
+    """Raised when a manifest violates the v1 contract."""
+
+
+def load_manifest(path: Path) -> dict:
+    """Load + validate a manifest. Raises ManifestError on violation."""
+    if not path.exists():
+        raise ManifestError(f"Manifest not found: {path}")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ManifestError(f"Manifest is not valid JSON: {path}: {exc}") from exc
+    errors = validate_manifest(data)
+    if errors:
+        raise ManifestError(
+            f"Manifest contract violations in {path}:\n  - " + "\n  - ".join(errors)
+        )
+    data["_manifest_dir"] = str(path.resolve().parent)
+    return data
+
+
+def validate_manifest(data: object) -> list[str]:
+    """Return a list of contract violations (empty = valid)."""
+    errors: list[str] = []
+    if not isinstance(data, dict):
+        return ["manifest must be a JSON object"]
+
+    for key in _REQUIRED_TOP:
+        if key not in data:
+            errors.append(f"missing required key: {key!r}")
+    if errors:
+        return errors
+
+    if data["manifest_version"] != MANIFEST_VERSION:
+        errors.append(
+            f"manifest_version {data['manifest_version']!r} unsupported "
+            f"(engine speaks v{MANIFEST_VERSION})"
+        )
+    if data["tier"] not in TIERS:
+        errors.append(f"tier {data['tier']!r} not in {TIERS}")
+
+    domains = data.get("domains")
+    if not isinstance(domains, dict) or not domains:
+        errors.append("domains must be a non-empty object")
+    else:
+        for name, cfg in domains.items():
+            if not isinstance(cfg, dict):
+                errors.append(f"domains.{name} must be an object")
+                continue
+            for key in _REQUIRED_DOMAIN_KEYS:
+                if key not in cfg:
+                    errors.append(f"domains.{name} missing {key!r}")
+            for key in ("search_cols", "output_cols"):
+                if key in cfg and (
+                    not isinstance(cfg[key], list) or not cfg[key]
+                ):
+                    errors.append(f"domains.{name}.{key} must be a non-empty list")
+
+    default_domain = data.get("default_domain")
+    if default_domain and isinstance(domains, dict) and default_domain not in domains:
+        errors.append(f"default_domain {default_domain!r} not in domains")
+
+    detect = data.get("detect")
+    if detect is not None:
+        if not isinstance(detect, dict):
+            errors.append("detect must be an object of domain → keyword list")
+        elif isinstance(domains, dict):
+            for name, kws in detect.items():
+                if name not in domains and name != "_stack":
+                    errors.append(f"detect.{name} references unknown domain")
+                if not isinstance(kws, list):
+                    errors.append(f"detect.{name} must be a list of keywords")
+
+    reasoning = data.get("reasoning")
+    if reasoning is not None:
+        if data.get("tier") == "lookup-only":
+            errors.append("reasoning block present but tier is lookup-only")
+        if not isinstance(reasoning, dict):
+            errors.append("reasoning must be an object")
+        else:
+            for key in _REQUIRED_REASONING_KEYS:
+                if key not in reasoning:
+                    errors.append(f"reasoning missing {key!r}")
+            plan = reasoning.get("plan")
+            if plan is not None:
+                if not isinstance(plan, dict):
+                    errors.append("reasoning.plan must be an object of domain → max_results")
+                elif isinstance(domains, dict):
+                    for name in plan:
+                        if name not in domains:
+                            errors.append(f"reasoning.plan.{name} references unknown domain")
+
+    stacks = data.get("stacks")
+    if stacks is not None:
+        if not isinstance(stacks, dict):
+            errors.append("stacks must be an object of stack-id → csv path")
+        elif "stack_cols" not in data:
+            errors.append("stacks present but stack_cols missing")
+
+    # Provenance discipline (ADR-061 §6) — a corpus without an owner rots.
+    for key in _REQUIRED_PROVENANCE:
+        if key not in data:
+            errors.append(f"missing provenance key: {key!r} (ADR-061 §6)")
+    upstream = data.get("upstream")
+    if isinstance(upstream, dict):
+        for key in ("repo", "sha", "last_checked"):
+            if key not in upstream:
+                errors.append(f"upstream missing {key!r}")
+    elif upstream is not None:
+        errors.append("upstream must be an object {repo, sha, last_checked}")
+
+    retriever = data.get("retriever")
+    if retriever is not None and retriever not in ("bm25", "structured", "hybrid"):
+        errors.append(f"retriever {retriever!r} unknown")
+
+    return errors
+
+
+def resolve_data_path(manifest: dict, relative: str) -> Path:
+    """Resolve a corpus file path relative to the manifest's directory.
+
+    Refuses absolute paths and parent-escapes — corpus files live beside
+    their manifest by contract (runtime-safety: read-only, local).
+    """
+    rel = Path(relative)
+    if rel.is_absolute() or ".." in rel.parts:
+        raise ManifestError(f"corpus path must be manifest-relative: {relative!r}")
+    base = Path(manifest.get("_manifest_dir", "."))
+    data_dir = manifest.get("data_dir", ".")
+    dd = Path(data_dir)
+    if dd.is_absolute() or ".." in dd.parts:
+        raise ManifestError(f"data_dir must be manifest-relative: {data_dir!r}")
+    return (base / dd / rel).resolve()

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

@@ -0,0 +1,129 @@
+---
+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
+
+Ground chart-type choice in the adopted data-viz corpus, not memory:
+`ground.py search --manifest <skills-root>/design-intelligence/data/manifest.json
+--domain chart "<data shape>"` → best chart type, when-NOT-to-use, volume
+threshold, a11y grade + colorblind fallback, library recommendation
+([`design-intelligence`](../design-intelligence/SKILL.md)).
+
+| 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/dist/agent-src/skills/database/SKILL.md

@@ -0,0 +1,111 @@
+---
+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
+
+
+> **Grounded corpus (Tier-1 consultation):** symptom → index/strategy
+> decisions come grounded — `ground.py search --manifest
+> <skills-root>/database/data/manifest.json "<symptom>"` → root cause,
+> strategy, good-code sketch, anti-pattern, verification probe (EXPLAIN
+> expectation). Corpus: [`data/query-tuning.csv`](data/query-tuning.csv)
+> (PostgreSQL 16 / MySQL 8-derived).
+
+## 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/dist/agent-src/skills/database/data/manifest.json

@@ -0,0 +1,35 @@
+{
+  "manifest_version": 1,
+  "domain": "db-query-tuning",
+  "tier": "lookup-only",
+  "retriever": "bm25",
+  "default_domain": "tuning",
+  "domains": {
+    "tuning": {
+      "file": "query-tuning.csv",
+      "search_cols": [
+        "Symptom",
+        "Keywords",
+        "Root Cause",
+        "Strategy"
+      ],
+      "output_cols": [
+        "Symptom",
+        "Root Cause",
+        "Strategy",
+        "Code Good",
+        "Anti-Pattern",
+        "Verification",
+        "Severity"
+      ],
+      "max_results": 3
+    }
+  },
+  "owner": "package-maintainer",
+  "refresh_cadence": "quarterly",
+  "upstream": {
+    "repo": "derived: PostgreSQL 16 + MySQL 8 reference docs",
+    "sha": "PostgreSQL 16.x / MySQL 8.4 docs",
+    "last_checked": "2026-06-07"
+  }
+}

package/dist/agent-src/skills/database/data/query-tuning.csv

@@ -0,0 +1,13 @@
+Symptom,Keywords,Root Cause,Strategy,Code Good,Anti-Pattern,Verification,Severity
+Slow WHERE on large table,slow query where filter full scan seq scan,Sequential scan despite selective predicate,B-tree index on the filtered column(s); composite index ordered by equality-first then range,"CREATE INDEX idx_orders_status_created ON orders (status, created_at)",Indexing low-cardinality boolean alone; composite ordered range-first,EXPLAIN (ANALYZE) shows Index Scan; rows estimate ≈ actual,HIGH
+ORDER BY ... LIMIT slow,order by limit sort top n latest,Sort node over the whole table for a top-N query,Index matching the ORDER BY direction (including DESC/NULLS) so LIMIT walks the index,CREATE INDEX idx_events_created_desc ON events (created_at DESC),OFFSET pagination for infinite feeds (use keyset),Plan shows Index Scan Backward / no Sort node,HIGH
+N+1 query loop,n+1 loop per row lazy load orm repeated query,Hundreds of identical queries differing only by id,Eager-load relations / batch with IN(...) or JOIN; dataloader pattern at the API layer,SELECT * FROM comments WHERE post_id IN (...),Fixing with a cache instead of the access pattern,Query count per request flat vs item count,HIGH
+LIKE '%term%' search,like contains search wildcard fulltext,Leading-wildcard LIKE can't use B-tree,Trigram index (pg_trgm GIN) or full-text search (tsvector + GIN); dedicated engine beyond ~10M rows,CREATE INDEX idx_users_name_trgm ON users USING gin (name gin_trgm_ops),Forcing LOWER() without an expression index,Plan shows Bitmap Index Scan on the GIN index,MEDIUM
+JOIN explosion,join many tables slow hash join nested loop,Mis-estimated join order / missing join keys index,Index every FK used in joins; verify row estimates; break monster joins into CTE/temp stages when estimates collapse,ANALYZE tables; index fk columns,Disabling nested loops globally; hint-chasing before stats are fresh,Estimates within ~10x of actuals at every join node,HIGH
+Aggregation over millions of rows,group by count sum report aggregate slow,Repeated full-table aggregation for dashboards,Pre-aggregate: materialized view / rollup table refreshed on schedule or trigger; partial indexes for hot subsets,CREATE MATERIALIZED VIEW daily_rev AS ... REFRESH CONCURRENTLY,Caching in app memory only (cold-start storms),"Dashboard reads hit the rollup, not base tables",MEDIUM
+Pagination deep offset,offset page 10000 slow deep pagination,OFFSET N scans+discards N rows,Keyset/cursor pagination on a unique ordered key,"WHERE (created_at,id) < (:c,:i) ORDER BY created_at DESC,id DESC LIMIT 20",Hiding offset behind a 'page' param and capping at 1000 as a fix,p99 latency flat across page depth,HIGH
+Write contention / lock waits,deadlock lock wait contention update hot row,"Hot-row updates serialize (counters, balances)",Row-level design: ledger inserts over UPDATE-in-place; batch with SKIP LOCKED queues; keep transactions short,SELECT ... FOR UPDATE SKIP LOCKED for workers,Retrying deadlocks blindly without ordering writes,Lock wait time ~0 under load test; deadlock rate 0,HIGH
+Missing/stale statistics,wrong plan estimate stale statistics analyze,Optimizer estimates wildly off → bad plans,Auto-analyze tuned for big tables; manual ANALYZE after bulk loads; extended statistics for correlated columns,"CREATE STATISTICS s_dist (dependencies) ON city,country FROM addr",Hinting every query instead of fixing stats,Plan estimates ≈ actuals after ANALYZE,MEDIUM
+Over-indexing writes,insert slow many indexes write amplification,Each extra index taxes every INSERT/UPDATE,Audit with index-usage stats; drop unused; covering index to replace several near-duplicates,pg_stat_user_indexes idx_scan = 0 candidates,Adding an index per slow query without retiring old ones,Write p95 recovers; no unused-index rows,MEDIUM
+SELECT * over wide rows,select star wide row toast network payload,Fetching unused columns (TOAST/LOB) dominates IO,Project needed columns; covering index enables index-only scans,"SELECT id,status,total FROM orders ...",Compressing payloads instead of trimming the select list,Plan shows Index Only Scan where applicable,LOW
+JSON column filtering,json jsonb attribute filter schemaless,Filtering inside JSON without index = full scan,"GIN index on jsonb path ops, or generated column + B-tree for hot keys",ALTER TABLE t ADD COLUMN status text GENERATED ALWAYS AS (doc->>'status') STORED; CREATE INDEX ...,Stuffing relational data into one JSON blob,Plan uses the GIN/generated-column index,MEDIUM

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

@@ -0,0 +1,188 @@
+---
+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
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# 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`](../../../docs/guidelines/agent-infra/5w2h-analysis.md) |
+| **L2 — Standard** | ~30 min | L1 + Critical Thinking, Inversion | + [`critical-thinking`](../../../docs/guidelines/agent-infra/critical-thinking.md), [`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md) |
+| **L3 — Deep** | ~60 min | L2 + Mental Models, First Principles, Systems Thinking, Six Hats | + [`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md), [`first-principles`](../../../docs/guidelines/agent-infra/first-principles.md), [`systems-thinking`](../../../docs/guidelines/agent-infra/systems-thinking.md), [`six-hats`](../../../docs/guidelines/agent-infra/six-hats.md) |
+| **L4 — Research** | 120 min+ | L3 + Cross-source comparison via web search | + [`comparison-matrix`](../../../docs/guidelines/agent-infra/comparison-matrix.md) |
+
+Every framework module is a project-local guideline under `docs/guidelines/agent-infra/`. Nothing is loaded from upstream at runtime.
+
+## 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`](../../../docs/guidelines/agent-infra/critical-thinking.md)) — 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`](../../../docs/guidelines/agent-infra/first-principles.md)) — strip to fundamental truths, validate each core assumption, rebuild from base.
+- **Systems Thinking** ([`systems-thinking`](../../../docs/guidelines/agent-infra/systems-thinking.md)) — map relationships, feedback loops, leverage points.
+- **Six Hats** ([`six-hats`](../../../docs/guidelines/agent-infra/six-hats.md)) — White (facts), Red (feelings), Black (cautions), Yellow (benefits), Green (creativity), Blue (process).
+
+**L4 addition:**
+
+- **Cross-source comparison** ([`comparison-matrix`](../../../docs/guidelines/agent-infra/comparison-matrix.md)) — 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
+
+- [`scqa-framework`](../../../docs/guidelines/agent-infra/scqa-framework.md) — situation / complication / question / answer decomposition.
+- [`5w2h-analysis`](../../../docs/guidelines/agent-infra/5w2h-analysis.md) — completeness check (7 questions).
+- [`critical-thinking`](../../../docs/guidelines/agent-infra/critical-thinking.md) — argument quality / fallacy detection.
+- [`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md) — pre-mortem on decisions, distinct from `adversarial-review`.
+- [`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md) — Munger's multi-discipline toolkit.
+- [`first-principles`](../../../docs/guidelines/agent-infra/first-principles.md) — fundamental-truth extraction.
+- [`systems-thinking`](../../../docs/guidelines/agent-infra/systems-thinking.md) — feedback loops + leverage points.
+- [`six-hats`](../../../docs/guidelines/agent-infra/six-hats.md) — White / Red / Black / Yellow / Green / Blue protocol.
+- [`comparison-matrix`](../../../docs/guidelines/agent-infra/comparison-matrix.md) — cross-source synthesis (L4 only).