tribunal-kit 6.0.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agent/.manifest.json +78 -0
- package/.agent/ARCHITECTURE.md +19 -241
- package/.agent/agents/accessibility-reviewer.md +23 -16
- package/.agent/agents/ai-code-reviewer.md +25 -21
- package/.agent/agents/anti-pattern-reviewer.md +12 -7
- package/.agent/agents/api-architect.md +1 -0
- package/.agent/agents/backend-specialist.md +23 -22
- package/.agent/agents/cloud-engineer.md +1 -0
- package/.agent/agents/code-archaeologist.md +1 -0
- package/.agent/agents/complexity-reviewer.md +10 -7
- package/.agent/agents/database-architect.md +3 -2
- package/.agent/agents/db-latency-auditor.md +6 -2
- package/.agent/agents/debugger.md +3 -2
- package/.agent/agents/dependency-reviewer.md +1 -0
- package/.agent/agents/devops-engineer.md +9 -8
- package/.agent/agents/documentation-writer.md +6 -5
- package/.agent/agents/explorer-agent.md +1 -0
- package/.agent/agents/frontend-reviewer.md +21 -17
- package/.agent/agents/frontend-specialist.md +23 -20
- package/.agent/agents/game-developer.md +1 -0
- package/.agent/agents/interaction-reviewer.md +10 -5
- package/.agent/agents/logic-reviewer.md +3 -0
- package/.agent/agents/minimalist-reviewer.md +6 -0
- package/.agent/agents/mobile-developer.md +7 -6
- package/.agent/agents/mobile-reviewer.md +14 -13
- package/.agent/agents/orchestrator.md +3 -0
- package/.agent/agents/penetration-tester.md +1 -0
- package/.agent/agents/performance-optimizer.md +6 -5
- package/.agent/agents/performance-reviewer.md +6 -6
- package/.agent/agents/pipeline-reviewer.md +144 -0
- package/.agent/agents/precedence-reviewer.md +1 -0
- package/.agent/agents/product-manager.md +1 -0
- package/.agent/agents/product-owner.md +1 -0
- package/.agent/agents/product-reviewer.md +12 -7
- package/.agent/agents/project-planner.md +3 -0
- package/.agent/agents/qa-automation-engineer.md +50 -43
- package/.agent/agents/resilience-reviewer.md +1 -0
- package/.agent/agents/schema-reviewer.md +1 -0
- package/.agent/agents/security-auditor.md +24 -24
- package/.agent/agents/seo-specialist.md +33 -23
- package/.agent/agents/sql-reviewer.md +5 -4
- package/.agent/agents/supervisor-agent.md +12 -2
- package/.agent/agents/swarm-worker-contracts.md +13 -13
- package/.agent/agents/swarm-worker-registry.md +51 -51
- package/.agent/agents/system-architect.md +1 -0
- package/.agent/agents/test-coverage-reviewer.md +25 -22
- package/.agent/agents/test-engineer.md +12 -11
- package/.agent/agents/throughput-optimizer.md +45 -40
- package/.agent/agents/type-safety-reviewer.md +5 -4
- package/.agent/agents/ui-ux-auditor.md +6 -4
- package/.agent/agents/ui-visual-auditor.md +3 -0
- package/.agent/agents/ux-reviewer.md +11 -6
- package/.agent/agents/visual-reviewer.md +11 -6
- package/.agent/agents/vitals-reviewer.md +5 -4
- package/.agent/history/memory/.memory.idx +3716 -1
- package/.agent/history/memory/MEMORY.md +246 -1
- package/.agent/mcp_config.json +1 -6
- package/.agent/routing_index.json +2034 -263
- package/.agent/rules/GEMINI.md +12 -10
- package/.agent/rules/GEMINI_PLANNER.md +19 -21
- package/.agent/scripts/_colors.js +52 -54
- package/.agent/scripts/_utils.js +52 -53
- package/.agent/scripts/auto_preview.js +39 -43
- package/.agent/scripts/bundle_analyzer.js +47 -60
- package/.agent/scripts/case_law_manager.js +200 -294
- package/.agent/scripts/checklist.js +73 -94
- package/.agent/scripts/cicd_validator.js +305 -0
- package/.agent/scripts/compile_router.py +4 -111
- package/.agent/scripts/context_broker.js +317 -412
- package/.agent/scripts/contract_engine.js +402 -0
- package/.agent/scripts/dependency_analyzer.js +112 -124
- package/.agent/scripts/graph_builder.js +75 -103
- package/.agent/scripts/graph_visualizer.js +10 -12
- package/.agent/scripts/graph_zoom.js +38 -55
- package/.agent/scripts/guardrail_engine.js +195 -145
- package/.agent/scripts/impact_classifier.js +55 -30
- package/.agent/scripts/inner_loop_validator.js +108 -159
- package/.agent/scripts/integrity_manifest.js +59 -67
- package/.agent/scripts/lint_runner.js +65 -75
- package/.agent/scripts/marathon_harness.js +131 -208
- package/.agent/scripts/migrate_skills_frontmatter.py +4 -63
- package/.agent/scripts/minify_context.js +29 -33
- package/.agent/scripts/minimal_change_engine.js +95 -87
- package/.agent/scripts/mutation_runner.js +46 -62
- package/.agent/scripts/pipeline_engine.js +320 -209
- package/.agent/scripts/prompt_compiler.js +118 -93
- package/.agent/scripts/schema_validator.js +73 -121
- package/.agent/scripts/security_scan.js +88 -117
- package/.agent/scripts/session_manager.js +52 -69
- package/.agent/scripts/signal_detector.js +24 -22
- package/.agent/scripts/skill_evolution.js +184 -245
- package/.agent/scripts/skill_integrator.js +35 -48
- package/.agent/scripts/socratic_gate_policy.js +15 -12
- package/.agent/scripts/strengthen_skills.js +29 -33
- package/.agent/scripts/swarm_dispatcher.js +120 -151
- package/.agent/scripts/test_runner.js +54 -56
- package/.agent/scripts/token_budget_broker.js +9 -7
- package/.agent/scripts/trace_engine.js +126 -0
- package/.agent/scripts/verify_all.js +76 -93
- package/.agent/scripts/visual_audit.js +16 -21
- package/.agent/skill_topic_map.json +237 -0
- package/.agent/skills/12-principles-of-animation/SKILL.md +7 -0
- package/.agent/skills/60fps-animation/SKILL.md +7 -0
- package/.agent/skills/accessible-animation/SKILL.md +5 -1
- package/.agent/skills/adapt/SKILL.md +7 -1
- package/.agent/skills/advanced-rag-pipelines/SKILL.md +1 -0
- package/.agent/skills/agent-organizer/SKILL.md +1 -0
- package/.agent/skills/agentic-patterns/SKILL.md +33 -25
- package/.agent/skills/agentic-workflows-2026/SKILL.md +80 -0
- package/.agent/skills/ai-app-hardening/SKILL.md +59 -0
- package/.agent/skills/ai-prompt-injection-defense/SKILL.md +7 -6
- package/.agent/skills/animation-on-scroll/SKILL.md +24 -15
- package/.agent/skills/animation-systems/SKILL.md +11 -10
- package/.agent/skills/antfu-conventions/SKILL.md +7 -2
- package/.agent/skills/api-patterns/SKILL.md +14 -10
- package/.agent/skills/api-security-auditor/SKILL.md +15 -14
- package/.agent/skills/app-builder/SKILL.md +1 -0
- package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +2 -2
- package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +1 -1
- package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +12 -12
- package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +3 -3
- package/.agent/skills/apple-design/SKILL.md +8 -7
- package/.agent/skills/architecture/SKILL.md +3 -2
- package/.agent/skills/audit-and-fix/SKILL.md +8 -5
- package/.agent/skills/authentication-best-practices/SKILL.md +9 -8
- package/.agent/skills/backend-security-expert/SKILL.md +1 -0
- package/.agent/skills/baseline-ui/SKILL.md +8 -7
- package/.agent/skills/bash-linux/SKILL.md +1 -0
- package/.agent/skills/behavioral-modes/SKILL.md +1 -0
- package/.agent/skills/better-colors/SKILL.md +11 -7
- package/.agent/skills/better-typography/SKILL.md +30 -16
- package/.agent/skills/better-ui/SKILL.md +17 -10
- package/.agent/skills/bolder/SKILL.md +6 -0
- package/.agent/skills/brainstorming/SKILL.md +6 -4
- package/.agent/skills/browser-native-ai/SKILL.md +5 -4
- package/.agent/skills/build-primitive/SKILL.md +5 -0
- package/.agent/skills/building-native-ui/SKILL.md +1 -0
- package/.agent/skills/cicd-pro/SKILL.md +2 -1
- package/.agent/skills/clarify/SKILL.md +19 -14
- package/.agent/skills/clean-code/SKILL.md +16 -15
- package/.agent/skills/cloud-architect/SKILL.md +1 -0
- package/.agent/skills/cobejs/SKILL.md +7 -9
- package/.agent/skills/code-review-checklist/SKILL.md +1 -0
- package/.agent/skills/codebase-design/SKILL.md +7 -2
- package/.agent/skills/colorize/SKILL.md +8 -3
- package/.agent/skills/compact-landing/SKILL.md +8 -3
- package/.agent/skills/company-logos/SKILL.md +6 -0
- package/.agent/skills/config-validator/SKILL.md +10 -9
- package/.agent/skills/containerization-pro/SKILL.md +6 -5
- package/.agent/skills/context-engineering-pro/SKILL.md +70 -0
- package/.agent/skills/create-design-md/SKILL.md +13 -5
- package/.agent/skills/critique/SKILL.md +10 -8
- package/.agent/skills/csharp-developer/SKILL.md +1 -0
- package/.agent/skills/data-validation-schemas/SKILL.md +28 -23
- package/.agent/skills/database-design/SKILL.md +2 -1
- package/.agent/skills/delight/SKILL.md +6 -0
- package/.agent/skills/deployment-procedures/SKILL.md +2 -1
- package/.agent/skills/design-lab/SKILL.md +5 -0
- package/.agent/skills/devops-engineer/SKILL.md +3 -2
- package/.agent/skills/devops-incident-responder/SKILL.md +2 -1
- package/.agent/skills/diagnosing-bugs/SKILL.md +12 -2
- package/.agent/skills/distill/SKILL.md +7 -2
- package/.agent/skills/documentation-templates/SKILL.md +3 -2
- package/.agent/skills/domain-modeling/SKILL.md +12 -4
- package/.agent/skills/duckdb-analytical-sql/SKILL.md +59 -0
- package/.agent/skills/edge-ai-mobile/SKILL.md +50 -0
- package/.agent/skills/edge-computing/SKILL.md +9 -8
- package/.agent/skills/emil-design-eng/SKILL.md +43 -27
- package/.agent/skills/error-resilience/SKILL.md +34 -16
- package/.agent/skills/expo-router-v4/SKILL.md +81 -0
- package/.agent/skills/extract-design-system/SKILL.md +12 -11
- package/.agent/skills/fabel-protocol/SKILL.md +24 -17
- package/.agent/skills/fixing-accessibility/SKILL.md +23 -16
- package/.agent/skills/fixing-metadata/SKILL.md +24 -13
- package/.agent/skills/fixing-motion-performance/SKILL.md +7 -5
- package/.agent/skills/framer-motion-expert/SKILL.md +29 -15
- package/.agent/skills/frontend-design/SKILL.md +21 -13
- package/.agent/skills/frontend-security-expert/SKILL.md +1 -0
- package/.agent/skills/game-design-expert/SKILL.md +1 -0
- package/.agent/skills/game-engineering-expert/SKILL.md +1 -0
- package/.agent/skills/generative-ui-expert/SKILL.md +3 -2
- package/.agent/skills/geo-fundamentals/SKILL.md +2 -1
- package/.agent/skills/git-pro/SKILL.md +10 -9
- package/.agent/skills/github-operations/SKILL.md +2 -1
- package/.agent/skills/gpt-taste/SKILL.md +7 -0
- package/.agent/skills/gsap-core/SKILL.md +26 -22
- package/.agent/skills/gsap-frameworks/SKILL.md +6 -5
- package/.agent/skills/gsap-performance/SKILL.md +4 -3
- package/.agent/skills/gsap-plugins/SKILL.md +34 -33
- package/.agent/skills/gsap-react/SKILL.md +9 -8
- package/.agent/skills/gsap-scrolltrigger/SKILL.md +34 -33
- package/.agent/skills/gsap-timeline/SKILL.md +18 -15
- package/.agent/skills/gsap-utils/SKILL.md +25 -24
- package/.agent/skills/harden/SKILL.md +9 -3
- package/.agent/skills/harness-protocol/SKILL.md +1 -0
- package/.agent/skills/i18n-localization/SKILL.md +10 -9
- package/.agent/skills/impeccable/SKILL.md +5 -0
- package/.agent/skills/improve-codebase-architecture/SKILL.md +10 -5
- package/.agent/skills/improve-ui/SKILL.md +12 -5
- package/.agent/skills/intelligent-routing/SKILL.md +7 -6
- package/.agent/skills/knowledge-graph/SKILL.md +1 -0
- package/.agent/skills/landing-page/SKILL.md +1 -0
- package/.agent/skills/lint-and-validate/SKILL.md +9 -4
- package/.agent/skills/llm-engineering/SKILL.md +55 -54
- package/.agent/skills/local-first/SKILL.md +20 -19
- package/.agent/skills/local-first-architecture/SKILL.md +6 -1
- package/.agent/skills/lottie-animation/SKILL.md +7 -3
- package/.agent/skills/marquee-loop/SKILL.md +1 -0
- package/.agent/skills/masked-reveal/SKILL.md +17 -4
- package/.agent/skills/mcp-builder/SKILL.md +13 -10
- package/.agent/skills/micro-interaction/SKILL.md +20 -5
- package/.agent/skills/mobile-design/SKILL.md +26 -15
- package/.agent/skills/monorepo-management/SKILL.md +3 -2
- package/.agent/skills/morphing-icons/SKILL.md +16 -6
- package/.agent/skills/motion-engineering/SKILL.md +19 -15
- package/.agent/skills/nextjs-react-expert/SKILL.md +26 -21
- package/.agent/skills/nodejs-best-practices/SKILL.md +89 -76
- package/.agent/skills/observability/SKILL.md +45 -44
- package/.agent/skills/opentelemetry-observability/SKILL.md +59 -0
- package/.agent/skills/page-transition-animation/SKILL.md +6 -3
- package/.agent/skills/parallel-agents/SKILL.md +7 -2
- package/.agent/skills/performance-profiling/SKILL.md +24 -13
- package/.agent/skills/plan-writing/SKILL.md +1 -0
- package/.agent/skills/platform-engineer/SKILL.md +3 -2
- package/.agent/skills/platform-engineering-opentofu/SKILL.md +68 -0
- package/.agent/skills/playwright-ai-e2e/SKILL.md +60 -0
- package/.agent/skills/playwright-best-practices/SKILL.md +29 -28
- package/.agent/skills/polish/SKILL.md +13 -12
- package/.agent/skills/powershell-windows/SKILL.md +1 -0
- package/.agent/skills/pricing-page/SKILL.md +8 -3
- package/.agent/skills/product-aware-heuristics/SKILL.md +122 -72
- package/.agent/skills/progressive-blur/SKILL.md +9 -4
- package/.agent/skills/project-idioms/SKILL.md +1 -0
- package/.agent/skills/property-based-testing/SKILL.md +58 -0
- package/.agent/skills/python-patterns/SKILL.md +1 -0
- package/.agent/skills/python-pro/SKILL.md +1 -0
- package/.agent/skills/quieter/SKILL.md +6 -0
- package/.agent/skills/react-doctor/SKILL.md +6 -0
- package/.agent/skills/react-specialist/SKILL.md +32 -28
- package/.agent/skills/readme-builder/SKILL.md +1 -0
- package/.agent/skills/realtime-patterns/SKILL.md +34 -33
- package/.agent/skills/red-team-tactics/SKILL.md +1 -0
- package/.agent/skills/redesign-skill/SKILL.md +6 -0
- package/.agent/skills/review-animations/SKILL.md +5 -2
- package/.agent/skills/review-animations/STANDARDS.md +37 -23
- package/.agent/skills/rust-pro/SKILL.md +1 -0
- package/.agent/skills/seo-fundamentals/SKILL.md +4 -3
- package/.agent/skills/server-management/SKILL.md +1 -0
- package/.agent/skills/shadcn-ui-expert/SKILL.md +28 -22
- package/.agent/skills/shape/SKILL.md +9 -2
- package/.agent/skills/skill-creator/SKILL.md +1 -0
- package/.agent/skills/soft-skill/SKILL.md +6 -0
- package/.agent/skills/sounds-on-the-web/SKILL.md +1 -0
- package/.agent/skills/sql-pro/SKILL.md +1 -0
- package/.agent/skills/supabase-postgres-best-practices/SKILL.md +1 -0
- package/.agent/skills/svg-animation/SKILL.md +16 -7
- package/.agent/skills/swiftui-expert/SKILL.md +1 -0
- package/.agent/skills/swiss-design/SKILL.md +5 -0
- package/.agent/skills/system-design-pro/SKILL.md +1 -0
- package/.agent/skills/systematic-debugging/SKILL.md +1 -0
- package/.agent/skills/tailwind-patterns/SKILL.md +25 -11
- package/.agent/skills/taste-skill/SKILL.md +6 -0
- package/.agent/skills/tdd-workflow/SKILL.md +5 -0
- package/.agent/skills/test-result-analyzer/SKILL.md +1 -0
- package/.agent/skills/testing-patterns/SKILL.md +123 -115
- package/.agent/skills/thermo-nuclear-code-quality-review/SKILL.md +5 -0
- package/.agent/skills/thinking-protocol/SKILL.md +3 -0
- package/.agent/skills/to-spring-or-not-to-spring/SKILL.md +9 -8
- package/.agent/skills/transitions-dev/SKILL.md +19 -6
- package/.agent/skills/trend-researcher/SKILL.md +1 -0
- package/.agent/skills/typescript-advanced/SKILL.md +23 -18
- package/.agent/skills/typeset/SKILL.md +10 -1
- package/.agent/skills/ui-reasoning-engine/SKILL.md +67 -48
- package/.agent/skills/ui-skill-packs/SKILL.md +6 -1
- package/.agent/skills/ui-skills-root/SKILL.md +39 -38
- package/.agent/skills/ui-ux-pro-max/SKILL.md +34 -26
- package/.agent/skills/ui-ux-researcher/SKILL.md +1 -0
- package/.agent/skills/vector-search-pgvector/SKILL.md +78 -0
- package/.agent/skills/vue-expert/SKILL.md +22 -19
- package/.agent/skills/vulnerability-scanner/SKILL.md +22 -21
- package/.agent/skills/web-accessibility-auditor/SKILL.md +2 -1
- package/.agent/skills/web-design-guidelines/SKILL.md +16 -10
- package/.agent/skills/web-quality-audit/SKILL.md +5 -0
- package/.agent/skills/webapp-testing/SKILL.md +14 -13
- package/.agent/skills/webgpu-performance/SKILL.md +1 -0
- package/.agent/skills/whimsy-injector/SKILL.md +9 -5
- package/.agent/skills/workflow-optimizer/SKILL.md +1 -0
- package/.agent/skills/zero-trust-passkeys/SKILL.md +90 -0
- package/.agent/templates/DESIGN.md +119 -110
- package/.agent/templates/design-tokens.json +9 -6
- package/.agent/workflows/acf.md +1 -0
- package/.agent/workflows/api-tester.md +1 -0
- package/.agent/workflows/audit.md +1 -0
- package/.agent/workflows/brainstorm.md +1 -0
- package/.agent/workflows/changelog.md +1 -0
- package/.agent/workflows/contract.md +60 -0
- package/.agent/workflows/create.md +1 -0
- package/.agent/workflows/debug.md +1 -0
- package/.agent/workflows/deploy.md +1 -0
- package/.agent/workflows/enhance.md +1 -0
- package/.agent/workflows/fix-ci.md +89 -0
- package/.agent/workflows/fix.md +1 -0
- package/.agent/workflows/generate.md +1 -0
- package/.agent/workflows/marathon.md +1 -0
- package/.agent/workflows/migrate.md +1 -0
- package/.agent/workflows/minimal.md +9 -7
- package/.agent/workflows/orchestrate.md +1 -0
- package/.agent/workflows/performance-benchmarker.md +1 -0
- package/.agent/workflows/pipeline.md +26 -21
- package/.agent/workflows/plan.md +1 -0
- package/.agent/workflows/preview.md +1 -0
- package/.agent/workflows/refactor.md +3 -2
- package/.agent/workflows/review-ai.md +4 -3
- package/.agent/workflows/review.md +1 -0
- package/.agent/workflows/session.md +1 -0
- package/.agent/workflows/status.md +1 -0
- package/.agent/workflows/strengthen-skills.md +1 -0
- package/.agent/workflows/super-prompt.md +1 -0
- package/.agent/workflows/swarm.md +15 -3
- package/.agent/workflows/test.md +8 -7
- package/.agent/workflows/tribunal-backend.md +3 -2
- package/.agent/workflows/tribunal-cicd.md +104 -0
- package/.agent/workflows/tribunal-database.md +1 -0
- package/.agent/workflows/tribunal-frontend.md +8 -6
- package/.agent/workflows/tribunal-full.md +15 -14
- package/.agent/workflows/tribunal-mobile.md +6 -5
- package/.agent/workflows/tribunal-performance.md +1 -0
- package/.agent/workflows/tribunal-speed.md +1 -0
- package/.agent/workflows/tribunal-ui.md +29 -21
- package/.agent/workflows/ui-ux-pro-max.md +19 -15
- package/CONTRIBUTING.md +3 -3
- package/README.md +160 -88
- package/SECURITY.md +11 -11
- package/bin/mcp-server.js +512 -233
- package/bin/tribunal-kit.js +29 -30
- package/bin/wrapper.js +45 -48
- package/dist/cli.js +26 -0
- package/dist/commands/case.js +2 -0
- package/dist/commands/contract.js +440 -0
- package/dist/commands/memory.js +3 -2
- package/dist/commands/native.js +36 -0
- package/dist/commands/status.js +6 -0
- package/dist/esm/index.mjs +32 -0
- package/dist/index.d.ts +58 -3
- package/package.json +20 -16
- package/scripts/benchmark.js +62 -86
- package/scripts/changelog.js +67 -73
- package/scripts/fix-vbc.js +13 -15
- package/scripts/fix-vbc.ps1 +2 -118
- package/scripts/stress_benchmark.js +358 -0
- package/scripts/sync-version.js +71 -41
- package/scripts/validate-payload.js +23 -30
- package/scripts/visual_audit.js +23 -13
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before attempting bug diagnostics or proposing code fixes, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Red-Capable Feedback Loop Rule (Section 34) → Construct a fast, deterministic, automated feedback loop command that reproduces the bug (goes red) BEFORE making code edits
|
|
24
25
|
2. Falsifiable Hypotheses Formulation (Section 107) → Formulate 3–5 falsifiable hypotheses (`"If X is cause, then Y prediction"`) before testing any single theory
|
|
25
26
|
3. Tagged Debug Logging & Cleanup (Section 123) → Tag debug log instrumentation (`[DEBUG-id]`) and sweep clean before finalizing regression fixes
|
|
@@ -66,6 +67,7 @@ Build the right feedback loop, and the bug is 90% fixed.
|
|
|
66
67
|
### Tighten the Loop
|
|
67
68
|
|
|
68
69
|
Treat the loop as a product. Once you have a loop, tighten it:
|
|
70
|
+
|
|
69
71
|
- **Can I make it faster?** (Cache setup, skip unrelated init, narrow the test scope.)
|
|
70
72
|
- **Can I make the signal sharper?** (Assert on the specific symptom, not "didn't crash".)
|
|
71
73
|
- **Can I make it more deterministic?** (Pin time, seed RNG, isolate filesystem, freeze network.)
|
|
@@ -79,21 +81,23 @@ The goal is not a clean repro but a higher reproduction rate. Loop the trigger 1
|
|
|
79
81
|
### When You Genuinely Cannot Build a Loop
|
|
80
82
|
|
|
81
83
|
Stop and say so explicitly. List what you tried. Ask the user for:
|
|
84
|
+
|
|
82
85
|
1. Access to whatever environment reproduces it.
|
|
83
86
|
2. A captured artifact (HAR file, log dump, core dump, screen recording with timestamps).
|
|
84
87
|
3. Permission to add temporary production instrumentation.
|
|
85
88
|
|
|
86
|
-
|
|
89
|
+
_Do not proceed to hypothesise without a loop._
|
|
87
90
|
|
|
88
91
|
### Phase 1 Completion Criterion — A Tight Loop That Goes Red
|
|
89
92
|
|
|
90
93
|
Phase 1 is done when the loop is tight and red-capable: you can name **one command** — a script path, a test invocation, a curl — that you have already run at least once (paste the invocation and its output), and that is:
|
|
94
|
+
|
|
91
95
|
- ✅ **Red-capable**: Drives the actual bug code path and asserts the user's exact symptom, going red on this bug and green once fixed. Not "runs without erroring" — it must catch this specific bug.
|
|
92
96
|
- ✅ **Deterministic**: Same verdict every run (or high, pinned reproduction rate).
|
|
93
97
|
- ✅ **Fast**: Seconds, not minutes.
|
|
94
98
|
- ✅ **Agent-runnable**: Runnable unattended (HITL only via `scripts/hitl-loop.template.sh`).
|
|
95
99
|
|
|
96
|
-
|
|
100
|
+
_If you catch yourself reading code to build a theory before this command exists, stop. No red-capable command, no Phase 2._
|
|
97
101
|
|
|
98
102
|
---
|
|
99
103
|
|
|
@@ -102,11 +106,13 @@ Phase 1 is done when the loop is tight and red-capable: you can name **one comma
|
|
|
102
106
|
Run the loop. Watch it go red — the bug appears.
|
|
103
107
|
|
|
104
108
|
### Confirm
|
|
109
|
+
|
|
105
110
|
1. The loop produces the failure mode the user described — not a different failure nearby. (Wrong bug = wrong fix.)
|
|
106
111
|
2. The failure is reproducible across multiple runs (or at a high enough reproduction rate).
|
|
107
112
|
3. You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix addresses it.
|
|
108
113
|
|
|
109
114
|
### Minimise
|
|
115
|
+
|
|
110
116
|
Once it's red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps one at a time, re-running the loop after each cut — keep only what's load-bearing for the failure.
|
|
111
117
|
|
|
112
118
|
> 🎯 **Why bother**: A minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
|
|
@@ -134,6 +140,7 @@ Show the ranked list to the user before testing. (Proceed with your ranking if t
|
|
|
134
140
|
Each probe must map to a specific prediction from Phase 3. Change one variable at a time.
|
|
135
141
|
|
|
136
142
|
### Tool Preference
|
|
143
|
+
|
|
137
144
|
1. **Debugger / REPL Inspection**: If the environment supports it. One breakpoint beats ten logs.
|
|
138
145
|
2. **Targeted Logs**: Place logs at boundaries that distinguish hypotheses. Never "log everything and grep".
|
|
139
146
|
3. **Tag Every Debug Log**: Prefix every debug log with a unique tag, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep.
|
|
@@ -150,6 +157,7 @@ A correct seam is one where the test exercises the real bug pattern as it occurs
|
|
|
150
157
|
If no correct seam exists, note it. The codebase architecture is preventing the bug from being locked down. Flag this for Phase 6.
|
|
151
158
|
|
|
152
159
|
### If a Correct Seam Exists:
|
|
160
|
+
|
|
153
161
|
1. Turn the minimised repro into a failing test at that seam.
|
|
154
162
|
2. Watch it fail.
|
|
155
163
|
3. Apply the fix.
|
|
@@ -161,6 +169,7 @@ If no correct seam exists, note it. The codebase architecture is preventing the
|
|
|
161
169
|
## Phase 6 — Cleanup + Post-Mortem
|
|
162
170
|
|
|
163
171
|
### Required Before Declaring Done
|
|
172
|
+
|
|
164
173
|
- [ ] Original repro no longer reproduces (re-run Phase 1 loop)
|
|
165
174
|
- [ ] Regression test passes (or absence of seam is documented)
|
|
166
175
|
- [ ] All `[DEBUG-...]` instrumentation removed (grep the prefix)
|
|
@@ -168,6 +177,7 @@ If no correct seam exists, note it. The codebase architecture is preventing the
|
|
|
168
177
|
- [ ] Correct hypothesis stated in commit / PR message
|
|
169
178
|
|
|
170
179
|
### Post-Mortem Handoff
|
|
180
|
+
|
|
171
181
|
Ask: **What would have prevented this bug?** If the answer involves architectural debt (no good test seam, tangled callers, hidden coupling), hand off to `/improve-codebase-architecture` with specific findings.
|
|
172
182
|
|
|
173
183
|
---
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before decluttering UI layouts, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Active screen components → Identify core primary user task and secondary/tertiary options
|
|
24
25
|
2. Container Reduction rules (Section 25) → Replace nested card containers and redundant borders with whitespace grid gaps
|
|
25
26
|
3. Progressive Disclosure patterns (Section 30) → Move advanced parameters into collapsible accordions or popovers
|
|
@@ -31,18 +32,22 @@ Systematically strip away visual clutter, redundant controls, and cognitive fric
|
|
|
31
32
|
## The 4 Distillation Steps
|
|
32
33
|
|
|
33
34
|
### 1. Identify & Remove Visual Noise
|
|
35
|
+
|
|
34
36
|
- **Container Reduction**: Eliminate unnecessary nested cards, boxes inside boxes, and decorative borders. Use whitespace instead of lines to separate content blocks.
|
|
35
37
|
- **Icon Pruning**: Remove decorative icons that restate obvious text labels (e.g. an envelope icon next to a button that clearly says "Send Email").
|
|
36
38
|
|
|
37
39
|
### 2. Collapse Secondary Actions
|
|
40
|
+
|
|
38
41
|
- **Primary vs Overflow**: Keep only 1 primary action button and max 1 secondary button visible. Hide tertiary actions inside an overflow dropdown (`...` menu).
|
|
39
42
|
- **Progressive Disclosure**: Hide advanced settings or non-essential controls behind an "Advanced Settings" accordion or popover.
|
|
40
43
|
|
|
41
44
|
### 3. Trim Copy & Microcopy
|
|
42
|
-
|
|
43
|
-
- **
|
|
45
|
+
|
|
46
|
+
- **Cut Conversational Filler**: Strip verbose instructions. Change _"Please fill out the form below to register your account"_ to _"Create account"_.
|
|
47
|
+
- **Shorten Button Labels**: Change _"Click here to update your profile settings"_ to _"Save profile"_.
|
|
44
48
|
|
|
45
49
|
### 4. Group Related Fields
|
|
50
|
+
|
|
46
51
|
- **Consolidate Form Inputs**: Merge separate "First Name" and "Last Name" fields into "Full Name" if separate values aren't strictly required. Merge city/state/zip into single address lookup where possible.
|
|
47
52
|
|
|
48
53
|
---
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before creating or editing documentation, API references, or comments, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Target Audience Identification (Section 27) → Match template strictly to audience (README for 10-min quickstart, API docs for payload contracts, Runbook for on-call triage)
|
|
24
25
|
2. Explain "Why", Not "What" in Code Comments (Section 147) → Document non-obvious business rules or bug workarounds; ban restating obvious code syntax
|
|
25
26
|
3. AI-Friendly Documentation Mapping (Section 171) → Maintain `ARCHITECTURE.md` and `@purpose:` annotations for codebase mental models and automated ingestion
|
|
@@ -149,8 +150,8 @@ Creates a new user account.
|
|
|
149
150
|
**Example**
|
|
150
151
|
\`\`\`bash
|
|
151
152
|
curl -X POST /api/users \
|
|
152
|
-
|
|
153
|
-
|
|
153
|
+
-H "Content-Type: application/json" \
|
|
154
|
+
-d '{"email": "user@example.com", "name": "Jane"}'
|
|
154
155
|
\`\`\`
|
|
155
156
|
```
|
|
156
157
|
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before designing domain entities or business modeling, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Ubiquitous Language Uniformity (Section 25) → Standardize 1 explicit term across UI, code, and DB (e.g. Customer vs User); ban interchangeable synonyms
|
|
24
25
|
2. Bounded Context Separation (Section 30) → Isolate models per context (e.g. Inventory Product vs Catalog Product); ban 60-column monolithic entities
|
|
25
26
|
3. Aggregate Root Invariants (Section 34) → Mutate child entities strictly through Aggregate Root methods (`order.addItem(...)`); ban direct child mutations
|
|
@@ -33,30 +34,37 @@ Model business domain concepts cleanly before committing to database schemas or
|
|
|
33
34
|
## 4 Domain Modeling Rules
|
|
34
35
|
|
|
35
36
|
### 1. Establish Ubiquitous Language
|
|
37
|
+
|
|
36
38
|
- Agree on strict, unambiguous terms used identically across domain experts, code variable names, database tables, and UI copy.
|
|
37
|
-
- ❌
|
|
39
|
+
- ❌ _User_, _Account_, _Member_, _Client_ used interchangeably for the same concept.
|
|
38
40
|
- ✅ Define 1 clear term: **Customer** (for billing context) vs **User** (for authentication context).
|
|
39
41
|
|
|
40
42
|
### 2. Define Bounded Contexts
|
|
41
|
-
|
|
43
|
+
|
|
44
|
+
- Separate large systems into distinct bounded contexts. An entity named `Product` in the _Inventory Context_ (stock level, warehouse bin) has different attributes than `Product` in the _Catalog Context_ (hero image, pricing).
|
|
42
45
|
|
|
43
46
|
### 3. Aggregates & Invariants
|
|
47
|
+
|
|
44
48
|
- An **Aggregate Root** (e.g. `Order`) enforces internal business invariants across child entities (`OrderItem`).
|
|
45
49
|
- Never mutate a child entity (`OrderItem`) directly without passing through the aggregate root method (`order.addItem(product, qty)`).
|
|
46
50
|
|
|
47
51
|
### 4. Value Objects Over Primitives
|
|
52
|
+
|
|
48
53
|
- Wrap primitives into type-safe Value Objects to enforce validation logic:
|
|
54
|
+
|
|
49
55
|
```typescript
|
|
50
56
|
// Value Object enforcing domain rule
|
|
51
57
|
export class EmailAddress {
|
|
52
58
|
private readonly value: string;
|
|
53
59
|
|
|
54
60
|
constructor(email: string) {
|
|
55
|
-
if (!email.includes(
|
|
61
|
+
if (!email.includes('@')) throw new Error('Invalid email domain');
|
|
56
62
|
this.value = email.toLowerCase().trim();
|
|
57
63
|
}
|
|
58
64
|
|
|
59
|
-
public toString(): string {
|
|
65
|
+
public toString(): string {
|
|
66
|
+
return this.value;
|
|
67
|
+
}
|
|
60
68
|
}
|
|
61
69
|
```
|
|
62
70
|
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: duckdb-analytical-sql
|
|
3
|
+
description: Embedded OLAP analytics, high-speed Parquet/JSON processing, in-memory analytical SQL, and DuckDB integrations in Node.js, Python, and WASM.
|
|
4
|
+
tools: Read, Grep, Glob, Edit, Write
|
|
5
|
+
version: 3.0.0
|
|
6
|
+
last-updated: 2026-08-05
|
|
7
|
+
script: .agent/scripts/schema_validator.js
|
|
8
|
+
scripts-binding:
|
|
9
|
+
- .agent/scripts/schema_validator.js
|
|
10
|
+
skills:
|
|
11
|
+
- sql-pro
|
|
12
|
+
- database-design
|
|
13
|
+
- performance-profiling
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# DuckDB Analytical SQL — Embedded Analytics
|
|
17
|
+
|
|
18
|
+
## Mandatory Pre-Flight Context Inspection
|
|
19
|
+
|
|
20
|
+
Before writing analytical queries:
|
|
21
|
+
|
|
22
|
+
1. Direct File Querying → Query Parquet/CSV/JSON directly without importing into a traditional DB
|
|
23
|
+
2. Memory Allocation → Set explicit memory limit (`SET max_memory = '4GB'`) to prevent OOM
|
|
24
|
+
3. Vectorized Engine Usage → Use column-oriented aggregation over line-by-line loops
|
|
25
|
+
|
|
26
|
+
## Node.js DuckDB Parquet Query Pattern
|
|
27
|
+
|
|
28
|
+
```typescript
|
|
29
|
+
import { Database } from 'duckdb-async';
|
|
30
|
+
|
|
31
|
+
export async function runAnalyticalReport(parquetGlobPath: string) {
|
|
32
|
+
const db = await Database.create(':memory:');
|
|
33
|
+
|
|
34
|
+
// Set memory limits for embedded execution
|
|
35
|
+
await db.exec("SET max_memory = '2GB'; SET threads = 4;");
|
|
36
|
+
|
|
37
|
+
const rows = await db.all(
|
|
38
|
+
`
|
|
39
|
+
SELECT
|
|
40
|
+
date_trunc('day', timestamp) as event_day,
|
|
41
|
+
event_type,
|
|
42
|
+
COUNT(*) as total_count,
|
|
43
|
+
QUANTILE_CONT(duration_ms, 0.95) as p95_latency
|
|
44
|
+
FROM read_parquet(?)
|
|
45
|
+
GROUP BY 1, 2
|
|
46
|
+
ORDER BY 1 DESC
|
|
47
|
+
LIMIT 100
|
|
48
|
+
`,
|
|
49
|
+
[parquetGlobPath],
|
|
50
|
+
);
|
|
51
|
+
|
|
52
|
+
return rows;
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## 🛑 Verification-Before-Completion (VBC) Protocol
|
|
57
|
+
|
|
58
|
+
- Verify query execution on sample Parquet dataset without loading entire file into RAM.
|
|
59
|
+
- Benchmark query throughput against memory constraints.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: edge-ai-mobile
|
|
3
|
+
description: On-device mobile AI, CoreML, Android NNAPI, ONNX Runtime Web/Mobile, local LLM execution (SLMs), and sub-10ms privacy-first edge inference.
|
|
4
|
+
tools: Read, Grep, Glob, Edit, Write
|
|
5
|
+
version: 3.0.0
|
|
6
|
+
last-updated: 2026-08-05
|
|
7
|
+
script: .agent/scripts/bundle_analyzer.js
|
|
8
|
+
scripts-binding:
|
|
9
|
+
- .agent/scripts/bundle_analyzer.js
|
|
10
|
+
skills:
|
|
11
|
+
- mobile-developer
|
|
12
|
+
- browser-native-ai
|
|
13
|
+
- performance-profiling
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Edge AI & On-Device Mobile Machine Learning
|
|
17
|
+
|
|
18
|
+
## Mandatory Pre-Flight Context Inspection
|
|
19
|
+
|
|
20
|
+
Before deploying on-device AI models:
|
|
21
|
+
|
|
22
|
+
1. Model Quantization → Use 4-bit/8-bit quantized models (GGUF/ONNX) to fit mobile RAM budgets (<500MB)
|
|
23
|
+
2. Hardware Acceleration → Bind inference engine to Apple Neural Engine (ANE) or Android NPU
|
|
24
|
+
3. Fallback Mechanism → Fall back gracefully to cloud LLM API if local inference exceeds latency budget (>200ms)
|
|
25
|
+
|
|
26
|
+
## Mobile ONNX Edge Inference Pattern
|
|
27
|
+
|
|
28
|
+
```typescript
|
|
29
|
+
import * as ort from 'onnxruntime-react-native';
|
|
30
|
+
|
|
31
|
+
export async function runLocalEmbeddings(textTokens: number[]): Promise<Float32Array> {
|
|
32
|
+
const session = await ort.InferenceSession.create('model_quantized.onnx', {
|
|
33
|
+
executionProviders: ['cpu'], // Accelerates via ANE/NNAPI internally
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
const tensor = new ort.Tensor('int64', new BigInt64Array(textTokens.map(BigInt)), [
|
|
37
|
+
1,
|
|
38
|
+
textTokens.length,
|
|
39
|
+
]);
|
|
40
|
+
const feeds = { input_ids: tensor };
|
|
41
|
+
|
|
42
|
+
const results = await session.run(feeds);
|
|
43
|
+
return results.embedding.data as Float32Array;
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## 🛑 Verification-Before-Completion (VBC) Protocol
|
|
48
|
+
|
|
49
|
+
- Verify local memory usage remains under 300MB during active model inference.
|
|
50
|
+
- Measure battery consumption impact.
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before engineering edge computing handlers or Cloudflare Workers, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Edge Runtime Restrictions (Section 25) → Strictly ban Node.js native core modules (`fs`, `child_process`, native `bcrypt`); use Web APIs (`fetch`, `crypto.subtle`)
|
|
24
25
|
2. Stale-While-Revalidate Caching (Section 47) → Use `Cache-Control: s-maxage=60, stale-while-revalidate=86400` and asynchronous `ctx.waitUntil()` cache puts
|
|
25
26
|
3. Edge Database Access (Section 81) → Never open direct raw TCP connections to DBs; use HTTP connection poolers (Prisma Accelerate, LibSQL, Supabase Pooler)
|
|
@@ -48,11 +49,11 @@ Edge functions (Cloudflare Workers, Vercel Edge) run on V8 Isolates, NOT standar
|
|
|
48
49
|
|
|
49
50
|
```typescript
|
|
50
51
|
// ❌ BAD: Attempting to use Node native core modules
|
|
51
|
-
import fs from
|
|
52
|
-
import bcrypt from
|
|
52
|
+
import fs from 'fs';
|
|
53
|
+
import bcrypt from 'bcrypt'; // Has C++ bindings, will instantly crash on V8 edge
|
|
53
54
|
|
|
54
55
|
// ✅ GOOD: Utilizing standard Web APIs (Fetch, CryptoKey)
|
|
55
|
-
const hashBuffer = await crypto.subtle.digest(
|
|
56
|
+
const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(password));
|
|
56
57
|
```
|
|
57
58
|
|
|
58
59
|
---
|
|
@@ -79,7 +80,7 @@ export default {
|
|
|
79
80
|
// Instructs the Edge CDN: Serve the stale version instantly to the user,
|
|
80
81
|
// but fire an async request in the background to update the cache for the next user.
|
|
81
82
|
response = new Response(response.body, response);
|
|
82
|
-
response.headers.set(
|
|
83
|
+
response.headers.set('Cache-Control', 's-maxage=60, stale-while-revalidate=86400');
|
|
83
84
|
|
|
84
85
|
// 4. Store in Cache asynchronously (do not block the user response)
|
|
85
86
|
ctx.waitUntil(cache.put(request, response.clone()));
|
|
@@ -104,14 +105,14 @@ Running logic globally while querying a monolithic database in `us-east-1` is co
|
|
|
104
105
|
|
|
105
106
|
```typescript
|
|
106
107
|
// ✅ Turso / LibSQL (Distributed Edge DB) usage:
|
|
107
|
-
import { createClient } from
|
|
108
|
+
import { createClient } from '@libsql/client/web';
|
|
108
109
|
|
|
109
110
|
const client = createClient({
|
|
110
111
|
url: env.TURSO_DATABASE_URL,
|
|
111
112
|
authToken: env.TURSO_AUTH_TOKEN,
|
|
112
113
|
});
|
|
113
114
|
|
|
114
|
-
const result = await client.execute(
|
|
115
|
+
const result = await client.execute('SELECT * FROM users WHERE id = ?', [userId]);
|
|
115
116
|
```
|
|
116
117
|
|
|
117
118
|
---
|
|
@@ -137,9 +138,9 @@ export class ChatRoom {
|
|
|
137
138
|
pair.server.accept();
|
|
138
139
|
|
|
139
140
|
// Handle incoming Chat messages
|
|
140
|
-
pair.server.addEventListener(
|
|
141
|
+
pair.server.addEventListener('message', msg => {
|
|
141
142
|
// Broadcast to all other connected edge users
|
|
142
|
-
this.sessions.forEach(
|
|
143
|
+
this.sessions.forEach(session => session.send(msg.data));
|
|
143
144
|
});
|
|
144
145
|
|
|
145
146
|
return new Response(null, { status: 101, webSocket: pair.client });
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before designing or reviewing UI micro-animations, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Frequency Gate (Section 54) → Never animate keyboard actions or high-frequency controls (100+ times/day); keep UI animations under 300ms
|
|
24
25
|
2. Easing Rule (Section 75) → Use strong `ease-out` (`cubic-bezier(0.23, 1, 0.32, 1)`) for entering UI elements; ban `ease-in`
|
|
25
26
|
3. Origin-Aware Popovers (Section 114) → Never animate scale from `scale(0)`; start at `scale(0.95)` with origin bound to trigger coordinates
|
|
@@ -35,44 +36,50 @@ You are a design engineer with the craft sensibility. You build interfaces where
|
|
|
35
36
|
## Core Philosophy
|
|
36
37
|
|
|
37
38
|
### Taste is trained, not innate
|
|
39
|
+
|
|
38
40
|
Good taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. Develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly.
|
|
39
41
|
|
|
40
42
|
### Unseen details compound
|
|
43
|
+
|
|
41
44
|
Most details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. Every decision below exists because the aggregate of invisible correctness creates interfaces people love without knowing why.
|
|
42
45
|
|
|
43
46
|
### Beauty is leverage
|
|
47
|
+
|
|
44
48
|
People select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Use beauty as leverage to stand out.
|
|
45
49
|
|
|
46
50
|
## Review Format (Required)
|
|
47
51
|
|
|
48
52
|
When reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:
|
|
49
53
|
|
|
50
|
-
| Before
|
|
51
|
-
|
|
|
52
|
-
| `transition: all 300ms`
|
|
53
|
-
| `transform: scale(0)`
|
|
54
|
-
| `ease-in` on dropdown
|
|
55
|
-
| No `:active` state on button | `transform: scale(0.97)` on `:active`
|
|
56
|
-
| `transform-origin: center`
|
|
54
|
+
| Before | After | Why |
|
|
55
|
+
| ---------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
56
|
+
| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |
|
|
57
|
+
| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
|
|
58
|
+
| `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |
|
|
59
|
+
| No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
|
|
60
|
+
| `transform-origin: center` | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers should scale from their trigger |
|
|
57
61
|
|
|
58
62
|
## The Animation Decision Framework
|
|
59
63
|
|
|
60
64
|
Before writing any animation code, answer these questions in order:
|
|
61
65
|
|
|
62
66
|
### 1. Should this animate at all?
|
|
67
|
+
|
|
63
68
|
**Ask:** How often will users see this animation?
|
|
64
69
|
|
|
65
|
-
| Frequency
|
|
66
|
-
|
|
|
67
|
-
| 100+ times/day (keyboard shortcuts, command palette)
|
|
68
|
-
| Tens of times/day (hover effects, list navigation)
|
|
69
|
-
| Occasional (modals, drawers, toasts)
|
|
70
|
-
| Rare/first-time (onboarding, feedback forms, celebrations) | Can add delight
|
|
70
|
+
| Frequency | Decision |
|
|
71
|
+
| ---------------------------------------------------------- | ---------------------------- |
|
|
72
|
+
| 100+ times/day (keyboard shortcuts, command palette) | No animation. Ever. |
|
|
73
|
+
| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
|
|
74
|
+
| Occasional (modals, drawers, toasts) | Standard animation |
|
|
75
|
+
| Rare/first-time (onboarding, feedback forms, celebrations) | Can add delight |
|
|
71
76
|
|
|
72
77
|
**Never animate keyboard-initiated actions.** These actions are repeated hundreds of times daily. Animation makes them feel slow and disconnected.
|
|
73
78
|
|
|
74
79
|
### 2. What is the purpose?
|
|
80
|
+
|
|
75
81
|
Valid purposes:
|
|
82
|
+
|
|
76
83
|
- **Spatial consistency**: toast enters/exits from the same direction.
|
|
77
84
|
- **State indication**: a morphing feedback button shows state change.
|
|
78
85
|
- **Explanation**: a marketing animation showing a feature.
|
|
@@ -82,45 +89,52 @@ Valid purposes:
|
|
|
82
89
|
If the purpose is just "it looks cool" and the user sees it often, don't animate.
|
|
83
90
|
|
|
84
91
|
### 3. What easing should it use?
|
|
92
|
+
|
|
85
93
|
Is the element entering or exiting?
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
94
|
+
Yes → ease-out (starts fast, feels responsive)
|
|
95
|
+
No →
|
|
96
|
+
Is it moving/morphing on screen?
|
|
97
|
+
Yes → ease-in-out (natural acceleration/deceleration)
|
|
98
|
+
Is it a hover/color change?
|
|
99
|
+
Yes → ease
|
|
100
|
+
Is it constant motion?
|
|
101
|
+
Yes → linear
|
|
102
|
+
Default → ease-out
|
|
95
103
|
|
|
96
104
|
**Critical: use custom easing curves.**
|
|
105
|
+
|
|
97
106
|
```css
|
|
98
107
|
/* Strong ease-out for UI interactions */
|
|
99
108
|
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);
|
|
100
109
|
/* Strong ease-in-out for on-screen movement */
|
|
101
110
|
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
|
|
102
111
|
```
|
|
112
|
+
|
|
103
113
|
**Never use ease-in for UI animations.** It makes the interface feel sluggish.
|
|
104
114
|
|
|
105
115
|
### 4. How fast should it be?
|
|
106
|
-
|
|
107
|
-
|
|
|
108
|
-
|
|
|
116
|
+
|
|
117
|
+
| Element | Duration |
|
|
118
|
+
| ------------------------ | --------- |
|
|
119
|
+
| Button press feedback | 100-160ms |
|
|
109
120
|
| Tooltips, small popovers | 125-200ms |
|
|
110
|
-
| Dropdowns, selects
|
|
111
|
-
| Modals, drawers
|
|
121
|
+
| Dropdowns, selects | 150-250ms |
|
|
122
|
+
| Modals, drawers | 200-500ms |
|
|
112
123
|
|
|
113
124
|
**Rule: UI animations should stay under 300ms.** Perception of speed matters as much as actual speed.
|
|
114
125
|
|
|
115
126
|
## Component Building Principles
|
|
116
127
|
|
|
117
128
|
### Buttons must feel responsive
|
|
129
|
+
|
|
118
130
|
Add `transform: scale(0.97)` on `:active` with subtle transition (160ms ease-out).
|
|
119
131
|
|
|
120
132
|
### Never animate from scale(0)
|
|
133
|
+
|
|
121
134
|
Start from `scale(0.95)` or higher combined with opacity.
|
|
122
135
|
|
|
123
136
|
### Make popovers origin-aware
|
|
137
|
+
|
|
124
138
|
Popovers should scale in from their trigger, not from center. Explicitly set `transform-origin` to the trigger coordinates (e.g., `var(--radix-popover-content-transform-origin)`). Modals are exempt as they are viewport-centered.
|
|
125
139
|
|
|
126
140
|
---
|
|
@@ -141,6 +155,7 @@ Popovers should scale in from their trigger, not from center. Explicitly set `tr
|
|
|
141
155
|
### ✅ Pre-Flight Self-Audit
|
|
142
156
|
|
|
143
157
|
Review these questions before confirming output:
|
|
158
|
+
|
|
144
159
|
```
|
|
145
160
|
✅ Did I justify the animation's existence based on frequency?
|
|
146
161
|
✅ Are all UI animations under 300ms?
|
|
@@ -152,5 +167,6 @@ Review these questions before confirming output:
|
|
|
152
167
|
### 🛑 Verification-Before-Completion (VBC) Protocol
|
|
153
168
|
|
|
154
169
|
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
|
|
170
|
+
|
|
155
171
|
- ❌ **Forbidden:** Declaring animation work complete because the code compiles.
|
|
156
172
|
- ✅ **Required:** Provide evidence that the animation executes flawlessly at 60fps in the browser, adhering to the 300ms budget and easing rules.
|
|
@@ -20,6 +20,7 @@ scripts-binding:
|
|
|
20
20
|
## Mandatory Pre-Flight Context Inspection
|
|
21
21
|
|
|
22
22
|
Before writing retry logic, circuit breakers, or error handling routines, you MUST inspect:
|
|
23
|
+
|
|
23
24
|
1. Idempotency Key Rule for Retries (Section 123) → Require explicit idempotency keys when retrying non-safe operations (POST/PUT); ban un-keyed retries
|
|
24
25
|
2. Exponential Backoff with Jitter (Section 106) → Implement randomized full jitter with capped exponential delays; ban fixed-delay retry loops
|
|
25
26
|
3. Operational vs Programmer Error Split (Section 28) → Catch and recover strictly from `OperationalError` instances; allow programmer bugs (`TypeError`) to crash fast
|
|
@@ -102,7 +103,12 @@ const DEFAULT_RETRY: RetryOptions = {
|
|
|
102
103
|
maxRetries: 3,
|
|
103
104
|
baseDelayMs: 500,
|
|
104
105
|
maxDelayMs: 15_000,
|
|
105
|
-
retryableErrors:
|
|
106
|
+
retryableErrors: err =>
|
|
107
|
+
err instanceof Error &&
|
|
108
|
+
(err.message.includes('ECONNRESET') ||
|
|
109
|
+
err.message.includes('ETIMEDOUT') ||
|
|
110
|
+
err.message.includes('503') ||
|
|
111
|
+
err.message.includes('429')),
|
|
106
112
|
};
|
|
107
113
|
|
|
108
114
|
async function withRetry<T>(fn: () => Promise<T>, options: Partial<RetryOptions> = {}): Promise<T> {
|
|
@@ -122,16 +128,19 @@ async function withRetry<T>(fn: () => Promise<T>, options: Partial<RetryOptions>
|
|
|
122
128
|
const capped = Math.min(exponential, opts.maxDelayMs);
|
|
123
129
|
const jitter = Math.random() * capped;
|
|
124
130
|
|
|
125
|
-
console.warn(
|
|
131
|
+
console.warn(
|
|
132
|
+
`[RETRY] Attempt ${attempt + 1}/${opts.maxRetries} failed. ` +
|
|
133
|
+
`Retrying in ${Math.round(jitter)}ms...`,
|
|
134
|
+
);
|
|
126
135
|
|
|
127
136
|
await sleep(jitter);
|
|
128
137
|
}
|
|
129
138
|
}
|
|
130
|
-
throw new Error(
|
|
139
|
+
throw new Error('Unreachable');
|
|
131
140
|
}
|
|
132
141
|
|
|
133
142
|
function sleep(ms: number): Promise<void> {
|
|
134
|
-
return new Promise(
|
|
143
|
+
return new Promise(resolve => setTimeout(resolve, ms));
|
|
135
144
|
}
|
|
136
145
|
|
|
137
146
|
// ❌ NEVER retry non-idempotent operations without idempotency keys
|
|
@@ -145,9 +154,9 @@ function sleep(ms: number): Promise<void> {
|
|
|
145
154
|
|
|
146
155
|
```typescript
|
|
147
156
|
enum CircuitState {
|
|
148
|
-
CLOSED =
|
|
149
|
-
OPEN =
|
|
150
|
-
HALF_OPEN =
|
|
157
|
+
CLOSED = 'CLOSED', // Normal — requests pass through
|
|
158
|
+
OPEN = 'OPEN', // Tripped — requests fail immediately
|
|
159
|
+
HALF_OPEN = 'HALF_OPEN', // Testing — one request allowed
|
|
151
160
|
}
|
|
152
161
|
|
|
153
162
|
class CircuitBreaker {
|
|
@@ -210,7 +219,7 @@ const paymentCircuit = new CircuitBreaker(5, 30_000);
|
|
|
210
219
|
|
|
211
220
|
const result = await paymentCircuit.execute(
|
|
212
221
|
() => paymentGateway.charge(amount),
|
|
213
|
-
() => ({ status:
|
|
222
|
+
() => ({ status: 'deferred', message: 'Payment queued for retry' }),
|
|
214
223
|
);
|
|
215
224
|
```
|
|
216
225
|
|
|
@@ -220,7 +229,7 @@ const result = await paymentCircuit.execute(
|
|
|
220
229
|
|
|
221
230
|
```tsx
|
|
222
231
|
// ✅ Error boundary with recovery
|
|
223
|
-
import { Component, type ReactNode } from
|
|
232
|
+
import { Component, type ReactNode } from 'react';
|
|
224
233
|
|
|
225
234
|
interface Props {
|
|
226
235
|
children: ReactNode;
|
|
@@ -251,7 +260,9 @@ class ErrorBoundary extends Component<Props, State> {
|
|
|
251
260
|
this.props.fallback ?? (
|
|
252
261
|
<div role="alert">
|
|
253
262
|
<h2>Something went wrong</h2>
|
|
254
|
-
<button onClick={() => this.setState({ hasError: false, error: null })}>
|
|
263
|
+
<button onClick={() => this.setState({ hasError: false, error: null })}>
|
|
264
|
+
Try Again
|
|
265
|
+
</button>
|
|
255
266
|
</div>
|
|
256
267
|
)
|
|
257
268
|
);
|
|
@@ -273,7 +284,10 @@ class ErrorBoundary extends Component<Props, State> {
|
|
|
273
284
|
|
|
274
285
|
```typescript
|
|
275
286
|
// ✅ AbortController-based timeout (modern, cancellable)
|
|
276
|
-
async function withTimeout<T>(
|
|
287
|
+
async function withTimeout<T>(
|
|
288
|
+
fn: (signal: AbortSignal) => Promise<T>,
|
|
289
|
+
timeoutMs: number,
|
|
290
|
+
): Promise<T> {
|
|
277
291
|
const controller = new AbortController();
|
|
278
292
|
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
279
293
|
|
|
@@ -290,7 +304,7 @@ async function withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, timeoutMs
|
|
|
290
304
|
}
|
|
291
305
|
|
|
292
306
|
// Usage
|
|
293
|
-
const data = await withTimeout(
|
|
307
|
+
const data = await withTimeout(signal => fetch('https://api.example.com/data', { signal }), 5000);
|
|
294
308
|
```
|
|
295
309
|
|
|
296
310
|
---
|
|
@@ -318,8 +332,8 @@ async function getUserProfile(userId: string): Promise<UserProfile> {
|
|
|
318
332
|
// Layer 3: Default
|
|
319
333
|
return {
|
|
320
334
|
id: userId,
|
|
321
|
-
name:
|
|
322
|
-
avatar:
|
|
335
|
+
name: 'Unknown User',
|
|
336
|
+
avatar: '/default-avatar.png',
|
|
323
337
|
_stale: true,
|
|
324
338
|
_default: true,
|
|
325
339
|
};
|
|
@@ -343,7 +357,11 @@ interface DeadLetter<T> {
|
|
|
343
357
|
originalQueue: string;
|
|
344
358
|
}
|
|
345
359
|
|
|
346
|
-
async function processWithDLQ<T>(
|
|
360
|
+
async function processWithDLQ<T>(
|
|
361
|
+
payload: T,
|
|
362
|
+
processor: (item: T) => Promise<void>,
|
|
363
|
+
dlqStore: { push: (item: DeadLetter<T>) => Promise<void> },
|
|
364
|
+
): Promise<void> {
|
|
347
365
|
try {
|
|
348
366
|
await withRetry(() => processor(payload), { maxRetries: 3 });
|
|
349
367
|
} catch (error) {
|
|
@@ -353,7 +371,7 @@ async function processWithDLQ<T>(payload: T, processor: (item: T) => Promise<voi
|
|
|
353
371
|
error: error instanceof Error ? error.message : String(error),
|
|
354
372
|
failedAt: new Date().toISOString(),
|
|
355
373
|
attempts: 4,
|
|
356
|
-
originalQueue:
|
|
374
|
+
originalQueue: 'main',
|
|
357
375
|
});
|
|
358
376
|
// Don't throw — the message is preserved for manual review
|
|
359
377
|
}
|