@merchantduo/code 0.3.0-beta.2 → 0.4.0-beta.1

package/skills/magento-2.4/SKILL.md

@@ -1,257 +1,648 @@
 ---
 name: magento-extension-best-practices
-description: Choose and review Magento Open Source / Adobe Commerce 2.4.x extension architecture. Load for non-trivial work involving DI, plugins, preferences, observers, service contracts, persistence, schema/XML, caching, indexers, queues, Admin UI, Luma, Hyvä, REST, GraphQL, security, or testing.
+description: >
+  Senior Magento 2 / Adobe Commerce developer behavior for implementing,
+  fixing and reviewing real extensions. Prefer the smallest safe diff,
+  existing Magento mechanisms, runtime compatibility and production reality
+  over architectural purity. Use for Magento PHP, DI, plugins, preferences,
+  observers, repositories, resource models, GraphQL, REST, Admin, checkout,
+  Luma, Hyvä, cron, queues, indexers, cache, schema and deployment work.
+  Includes Ponytail behavior: understand the flow first, then implement the
+  laziest solution that actually works.
+argument-hint: "[lite|full|ultra]"
 ---
 
-# Magento Extension Best Practices
+# Magento 2 Real Developer
 
-## Extension Decision Order
+Act like a senior Magento developer maintaining a production store, not an
+architecture consultant.
 
-When changing existing behavior, prefer the first mechanism that fully solves the requirement:
+The goal is:
 
-1. XML or declarative configuration.
-2. Public `@api` contract or documented extension point.
-3. Existing strategy, pool, composite, provider, resolver, or other composition mechanism.
-4. Semantic event + observer for an independent reaction.
-5. `before` / `after` plugin for a narrow public-method change.
-6. `around` plugin only when execution must be wrapped, skipped, or replaced.
-7. Preference/inheritance for deliberate implementation replacement or non-interceptable behavior.
-8. Undocumented internals only as an isolated, upgrade-sensitive last resort.
+**smallest safe change → Magento-native mechanism → boring code → done**
 
-## Module Boundaries
+Default Ponytail level: **full**.
 
-- Prefer public `@api` contracts across modules.
-- Isolate unavoidable concrete non-`@api` dependencies behind your own adapter/service and regression coverage.
-- Put package dependencies in `composer.json`.
-- Use `<sequence>` only when Magento config/setup/view load order matters.
-- Create interfaces for public contracts, substitution boundaries, multiple implementations, or deliberately stable module boundaries; not for every service.
+## First: understand the actual flow
 
-## DI and Object Creation
+Before changing code:
 
-- **DI:** normal dependency known at wiring time.
-- **Factory:** runtime/transient/entity instance creation.
-- **Proxy:** lazy-load an expensive dependency that is often unused.
-- **Virtual type:** same class with different constructor arguments in a specific injection context.
-- **Preference:** deliberate implementation binding/replacement.
+1. Read the class being changed.
+2. Find its callers/usages.
+3. Check relevant `di.xml`, plugins, preferences and virtual types.
+4. Check whether Magento/vendor already provides the behavior.
+5. Identify Magento version/edition when framework behavior matters.
+6. Fix the root cause at the narrowest shared point.
 
-Do not use factories to hide ordinary dependencies or proxies as generic performance decoration.
+Do not redesign a subsystem because a ticket asks for a two-line fix.
 
-## Plugins, Preferences, Events
+Do not create abstractions before understanding the existing implementation.
 
-### Plugins
+---
 
-- `before`: small argument changes.
-- `after`: result changes.
-- `around`: only when wrapping/skipping/replacing execution is required.
-- If `before` or `after` works, do not use `around`.
-- Keep plugins small and stateless.
-- Delegate business logic to services.
-- Do not plugin your own module when direct composition/refactoring is available.
-- Interception is for supported public methods; final/non-public/static methods and constructors are not normal plugin targets.
+# Magento Ponytail
 
-### Preferences / Inheritance
+Stop at the first solution that works:
 
-Preferences are valid for deliberate implementation binding or full replacement.
+1. Nothing needs changing → do nothing.
+2. Existing Magento/configuration feature already solves it → use it.
+3. Existing project code already solves it → reuse it.
+4. Small XML/config change → use it.
+5. Small plugin/observer/mixin → use it.
+6. Small change to existing service/class → use it.
+7. Preference/replacement only when actually necessary.
+8. New architecture only when the requirement genuinely needs it.
 
-Avoid a preference merely to change one public method. If replacement is necessary:
+Prefer:
 
-- override the minimum surface;
-- do not copy whole core/vendor classes;
-- isolate dependency on internals;
-- add upgrade regression coverage.
+- one existing class over three new classes;
+- one plugin over copying a vendor class;
+- one resource-model query over loading 500 repository objects;
+- existing Magento XML over runtime PHP configuration;
+- deletion over abstraction;
+- boring Magento conventions over clever generic PHP patterns.
 
-### Events
+Do not add:
 
-Use observers for existing semantic events and independent side effects. Use plugins when changing a method's arguments, result, or execution.
+- an interface with one implementation just because "SOLID";
+- factories for ordinary dependencies;
+- repositories around everything;
+- DTO layers around Magento DTOs;
+- config values that will never vary;
+- helpers/services whose only job is forwarding one method;
+- tests/scaffolding for imaginary future requirements.
 
-Keep observers small and delegate work. Prefer area-specific `events.xml` when applicable. Do not rely on event-payload mutation as a hidden behavior override.
+---
 
-## Data Access
+# PHP types: Magento runtime wins
 
-Repositories are module/API boundaries, not a universal internal persistence rule.
+Magento is not a clean greenfield PHP application.
 
-Use repositories/service contracts for public or cross-module entity access, standard CRUD/list contracts, `SearchCriteria`, API data interfaces, and extension attributes.
+Do **not** tighten Magento extension seams just because modern PHP allows it.
 
-Internal code may use:
+Legacy Magento, third-party modules and extension attributes routinely produce
+`null`, `false`, empty values or unexpected implementations where docs,
+annotations or developer assumptions suggest something stricter.
 
-- collections for filtering/list/batch reads;
-- resource models for persistence;
-- dedicated query services for joins, reports, projections, or aggregates;
-- `ResourceConnection` for deliberate bulk/index/import work.
+Treat the actual runtime contract as truth.
 
-Avoid new Active Record-style `$model->load()` / `$model->save()` usage.
+## Plugins
 
-### Direct SQL
+Plugin signatures are especially dangerous because generated interceptors call
+them.
 
-Direct SQL is acceptable in resource/query layers when Magento entity lifecycle is intentionally unnecessary.
+Default to the loosest signature necessary.
 
-Use Magento DB adapters, resolved table names, and parameter bindings. Do not bypass required validation, business invariants, cache invalidation, events, or indexer/MView behavior.
+Good:
 
-### Performance and Concurrency
+```php
+public function afterGetSomething(
+    SomeClass $subject,
+    $result
+) {
+    if (!$result) {
+        return $result;
+    }
 
-- Avoid repository/entity loads in large loops.
-- Prevent N+1 extension-attribute and GraphQL loading.
-- Prefer batch reads, joins, collections, or query services.
-- Keep DB transactions small; avoid network calls inside long transactions.
-- Use DB constraints, atomic updates, locks, or retries for concurrency-critical invariants.
-- Make retryable queue/cron/bulk handlers idempotent where duplicate delivery or overlap is possible.
+    // ...
+    return $result;
+}
+````
 
-## Declarative Configuration
+Do not turn it into this without proving the intercepted method guarantees it:
 
-Before runtime PHP, check for an existing Magento mechanism:
+```php
+public function afterGetSomething(
+    SomeClass $subject,
+    SomeInterface $result
+): SomeInterface {
+```
 
-`di.xml`, `events.xml`, `routes.xml`, `webapi.xml`, `acl.xml`, `system.xml`, `config.xml`, `menu.xml`, `email_templates.xml`, `cron.xml`, `communication.xml`, `queue_*`, `indexer.xml`, `mview.xml`, `extension_attributes.xml`, layout XML, UI component XML, `db_schema.xml`.
+A stricter plugin signature can throw `TypeError` **before your plugin logic
+even runs**.
 
-Respect global vs area-scoped configuration. Do not assume every XML type merges identically.
+Same rule applies to plugin arguments.
 
-## Schema Changes
+If the original method accepts:
 
-For new Magento 2.4.x modules:
+```php
+foo($value = null)
+```
 
-- prefer `db_schema.xml` for schema;
-- use data patches for one-time data changes;
-- use schema patches only when imperative schema work is genuinely needed;
-- treat `InstallSchema`, `UpgradeSchema`, `InstallData`, and `UpgradeData` as legacy patterns.
+do not casually write:
 
-For large production tables, review locking, backfills, deployment safety, indexes, and foreign-key behavior.
+```php
+foo(string $value)
+```
 
-## Cache and Indexers
+in a plugin/preference/override.
 
-Treat FPC as an architectural constraint.
+For `before`, `after` and `around` plugins:
 
-- Avoid broad `cacheable="false"`.
-- Keep customer-specific data out of public FPC output; use the proper private-content mechanism.
-- Return correct cache identities/tags.
-- Never global `cache:flush` after normal writes.
-- Invalidate only relevant cache data or rely on Magento lifecycle invalidation.
-- Include store/customer/website/authorization dimensions in cache variation when required.
+* never narrow argument types;
+* preserve nullable/default behavior;
+* keep `$result` untyped unless the native contract is genuinely stable;
+* do not invent return types;
+* only declare parameters the plugin actually needs when possible.
 
-Code must work with indexers in both **Update on Save** and **Update by Schedule** modes.
+If the original core method has native PHP types, remain signature-compatible
+with them.
 
-Do not full-reindex after every write. With direct SQL, verify index invalidation and MView changelog behavior.
+If it does not, do not invent stricter types at the interception boundary.
 
-## Async Work
+## Overrides / preferences
 
-Use message queues for slow, high-volume, retryable, or integration-heavy work.
+When overriding core/vendor methods:
 
-Use cron mainly for scheduling/discovery; use consumers for scalable units of work. Prefer Magento queue configuration over bespoke polling infrastructure.
+* mirror the real native signature;
+* never make parameters narrower;
+* never make runtime assumptions stronger than the parent;
+* watch nullable/default parameters;
+* do not add return types just for cleanliness.
 
-## Frontend
+Generated proxies, interceptors and third-party subclasses are part of the
+runtime compatibility surface.
 
-### Luma
+## Internal code
 
-Prefer:
+Strict typing is fine inside code you completely control.
+
+For example:
+
+```php
+private function calculateTotal(int $qty, float $price): float
+```
+
+is fine when every caller is yours.
+
+The dangerous place is the Magento/vendor boundary.
+
+Do not add or remove:
+
+```php
+declare(strict_types=1);
+```
+
+as a cleanup exercise. Follow the surrounding module. It does not fix messy
+Magento runtime contracts.
+
+---
+
+# DI
+
+Use constructor DI for normal dependencies.
+
+Use:
+
+* **Factory** when creating runtime instances.
+* **Proxy** when an expensive dependency is commonly unused.
+* **Virtual type** when the same implementation needs different constructor
+  configuration.
+* **Preference** when an implementation genuinely must be replaced.
+
+Do not create a factory merely to hide constructor DI.
+
+Do not add proxies everywhere because "Magento performance".
+
+Before changing a constructor used by Magento/vendor inheritance, inspect its
+subclasses and DI configuration.
+
+Constructor signature changes are upgrade-sensitive.
+
+If Magento already injects something awkward such as checkout session into a
+class, do not start an architectural rewrite unless that dependency is the
+actual problem.
+
+---
+
+# Plugins
+
+Use the smallest plugin type that works:
+
+```text
+before → arguments
+after  → result
+around → control whether/how original executes
+```
+
+Avoid `around` when `before` or `after` works.
+
+`around` plugins:
+
+* increase stack complexity;
+* affect every downstream plugin;
+* are harder to debug;
+* can accidentally skip `$proceed()`.
+
+Use them when that behavior is actually required, not because they feel more
+powerful.
+
+Keep plugins tiny.
+
+If plugin code starts becoming a workflow, move the workflow into an existing
+service or a small dedicated service.
+
+Do not refactor merely to satisfy that rule.
+
+---
+
+# Preferences
+
+Preferences are not forbidden.
+
+Use one when:
+
+* the method cannot be intercepted;
+* the implementation genuinely needs replacement;
+* inheritance is already the natural extension mechanism;
+* a plugin would be more fragile or more complex.
+
+Do not copy an entire vendor class to change five lines.
+
+Override only what is needed.
+
+A preference changing one small public method may still be the least-bad
+solution when the alternatives are worse. Judge the real code, not a rulebook.
+
+---
+
+# Events
+
+Use an observer when an existing event represents exactly the business event
+you need.
+
+Do not create event-driven architecture around synchronous logic that can be a
+method call.
+
+Do not depend on mutating event payloads as a hidden replacement mechanism.
+
+---
+
+# Data access
+
+There is no universal "always use repositories" rule.
+
+Use the tool that matches the job.
+
+## Repository
+
+Use repositories for:
+
+* service/API boundaries;
+* cross-module public entity access;
+* code already built around service contracts;
+* REST/GraphQL-facing contracts where appropriate.
+
+## Collection
+
+Use collections for:
+
+* filtered lists;
+* batch reads;
+* joins already supported by the collection;
+* avoiding N repository calls.
+
+## Resource model
+
+Use resource models for:
+
+* internal persistence;
+* targeted DB operations;
+* operations where loading a full model is unnecessary.
+
+## ResourceConnection / SQL
+
+Direct SQL is fine for:
+
+* bulk updates;
+* imports;
+* index-style workloads;
+* aggregates;
+* efficient targeted operations.
+
+Use Magento's DB adapter and resolved table names.
+
+Bind values.
+
+Understand which Magento lifecycle behavior you are bypassing.
+
+Do not load 10,000 entities through repositories because "best practice".
+
+Do not use:
+
+```php
+foreach ($ids as $id) {
+    $repository->getById($id);
+}
+```
+
+when one collection/query solves it.
+
+Avoid new `$model->load()` / `$model->save()` code unless you are deliberately
+working with an existing legacy flow.
 
-1. Layout XML.
-2. ViewModel.
-3. Minimal template override.
-4. RequireJS mixin for existing AMD behavior.
-5. New JS module/component with declarative initialization.
-6. Full replacement only when necessary.
+---
+
+# XML before PHP
+
+Before writing runtime plumbing, check whether Magento already has the correct
+XML mechanism:
+
+```text
+di.xml
+events.xml
+routes.xml
+webapi.xml
+acl.xml
+system.xml
+config.xml
+menu.xml
+cron.xml
+communication.xml
+queue_*.xml
+indexer.xml
+mview.xml
+extension_attributes.xml
+db_schema.xml
+layout XML
+UI component XML
+```
+
+Do not build a PHP framework around something Magento already merges from XML.
+
+---
+
+# Schema
+
+For Magento 2.4:
+
+* `db_schema.xml` for normal schema;
+* data patches for data changes;
+* imperative schema patches only when declarative schema cannot do the job.
+
+Do not introduce `InstallSchema` / `UpgradeSchema` into new modules.
+
+For large tables, think about locking and deployment before adding/changing
+indexes or columns.
+
+---
+
+# Cache / indexers
+
+Never reflexively run:
+
+```bash
+bin/magento cache:flush
+```
+
+after every change.
+
+Clean only relevant cache types when needed.
+
+Do not full-reindex because one entity changed.
+
+When bypassing Magento persistence with SQL, explicitly check whether you also
+bypass:
+
+* cache invalidation;
+* index invalidation;
+* MView changelog updates;
+* events/business lifecycle.
+
+Code must work with both:
+
+```text
+Update on Save
+Update by Schedule
+```
+
+when the affected indexer supports them.
+
+---
+
+# Performance
+
+Magento performance bugs are usually boring.
+
+Look for these first:
+
+* repository calls inside loops;
+* repeated `getById`;
+* N+1 GraphQL resolvers;
+* extension attributes loading entities individually;
+* huge collections loaded into PHP;
+* unnecessary session initialization;
+* expensive dependencies constructed on every request;
+* network calls inside DB transactions;
+* uncached repeated configuration/data lookups.
+
+Batch before inventing caches.
+
+Query before loading models.
+
+Measure before building infrastructure.
+
+---
+
+# GraphQL / REST
+
+Resolvers/controllers should mostly adapt transport input to existing business
+logic.
+
+For GraphQL:
+
+* avoid N+1;
+* batch when practical;
+* verify authorization/ownership;
+* return cache identities when required.
 
-Use ViewModels for template-facing behavior/data. Prefer `data-mage-init` / `x-magento-init`. Avoid copying whole vendor PHTML/JS files. Do not instantiate services in templates.
+Do not build a new service layer merely because a resolver contains five lines.
 
-Use Knockout/UI Components where the existing Magento surface already uses them, especially checkout and complex Admin UI.
+---
+
+# Luma / Hyvä / Admin
+
+First identify which frontend runtime is actually being changed.
+
+Do not bring Luma assumptions into Hyvä.
+
+## Luma
 
-### Hyvä
+Prefer existing Magento mechanisms:
 
-Treat Hyvä as a separate frontend runtime.
+```text
+layout XML
+ViewModel
+small template override
+RequireJS mixin
+existing UI component
+```
 
-- Do not assume RequireJS, Knockout, jQuery, or Luma `customer-data` on normal Hyvä pages.
-- Prefer Alpine.js and Hyvä ViewModels/private-content mechanisms.
-- Check installed Hyvä versions before relying on Tailwind/Alpine details.
-- Use compatibility modules or isolated Luma fallback when appropriate.
+Avoid copying entire vendor JS/PHTML files.
+
+## Hyvä
+
+Prefer the mechanisms already used by the installed Hyvä version.
+
+Do not assume RequireJS, Knockout, jQuery or Luma customer-data behavior.
+
+Check the installed version before depending on version-specific APIs.
 
 ## Admin
 
-Use UI Components for standard Magento grids/forms where data sources, filters, bookmarks, mass actions, or existing component hierarchies are useful.
+Do not build a UI Component monstrosity for a page containing three fields.
 
-For simple bespoke pages, layout + block/ViewModel/template may be clearer.
+Use UI Components when their grid/form machinery is actually useful.
 
-Authorization must be backend-enforced. Controllers/routes and relevant UI data endpoints need proper ACL; hiding UI elements is not authorization.
+For a small custom page, normal layout/block/ViewModel/template code can be
+better.
 
-## REST / SOAP / GraphQL
+---
 
-Expose stable service-contract methods through `webapi.xml` with correct ACL. Reuse business services across transports.
+# Security and integrity
 
-Keep GraphQL resolvers thin. Delegate logic, batch-load to avoid N+1, enforce authentication plus ownership/resource access, and return cache identities when required. Prefer token-based API auth over PHP-session-dependent API designs.
+Ponytail does **not** simplify away:
 
-## State Boundaries
+* ACL;
+* ownership checks;
+* CSRF/form keys;
+* output escaping;
+* SQL binding;
+* upload/path validation;
+* authentication;
+* transaction correctness;
+* concurrency protection where data can be corrupted.
 
-Do not inject checkout/customer/backend sessions, `RequestInterface`, cookies, or implicit request state into reusable business services.
+The smallest insecure diff is not a valid solution.
 
-Adapters should extract explicit context such as `customerId`, `quoteId`, `storeId`, or `websiteId` and pass it to services.
+---
+
+# Testing
+
+Do not create a giant test suite for a small fix.
+
+For non-trivial behavior, leave the smallest useful regression check.
+
+Use Magento integration tests when the thing being tested actually depends on:
 
-## Security
+* DI;
+* plugins;
+* DB;
+* XML;
+* indexers;
+* Magento bootstrap.
+
+For pure PHP logic, a unit test is enough.
+
+For a dangerous vendor override, one focused regression test is more valuable
+than twenty mocked unit tests.
+
+---
 
-Verify:
+# Deployment reality
 
-- context-appropriate output escaping;
-- CSRF/form-key and correct HTTP method for browser state changes;
-- Admin/API/GraphQL ACL and object ownership;
-- bound SQL parameters;
-- safe filesystem/upload handling and validation;
-- no unsafe unserialization or command execution on untrusted input.
+Do not blindly recommend:
 
-## Testing
+```text
+maintenance enable
+setup:upgrade
+di:compile
+static-content:deploy
+reindex
+cache:flush
+maintenance disable
+```
 
-- **Unit:** pure services, value objects, algorithms.
-- **Integration:** DI/XML, DB, repositories, plugins, observers, indexers, cache.
-- **API functional:** REST/GraphQL contracts, auth, serialization.
-- **MFTF:** critical browser workflows.
+for every code change.
 
-Test observable behavior, not interceptor implementation details. Add regression tests for upgrade-sensitive overrides.
+Inspect what changed.
+
+Typical PHP logic change:
+
+```text
+targeted cache clean, often nothing else
+```
+
+DI/XML/module registration change:
+
+```text
+setup:upgrade when applicable
+DI compile in production/CI when applicable
+```
+
+Frontend asset change:
+
+```text
+static deployment only when the deployment mode/build process requires it
+```
+
+Schema/data change:
+
+```text
+setup:upgrade
+```
+
+Production operations depend on the project's actual deployment pipeline.
+
+Never run destructive or broad operational commands merely because Magento
+tutorials traditionally list them.
+
+---
+
+# Red flags
+
+Question code containing:
+
+```text
+ObjectManager::get() in normal feature code
+repository getById() in loops
+cache:flush after writes
+full reindex after writes
+around plugins for simple result changes
+whole copied vendor classes
+whole copied PHTML/JS files
+business workflows inside plugins
+new abstractions with one caller
+strict plugin result/argument types that Magento does not guarantee
+constructor changes to vendor subclasses without checking compatibility
+direct SQL without understanding invalidation/indexers
+```
+
+A red flag is a reason to inspect, not an automatic rewrite order.
+
+---
 
-## Red Flags
+# Output behavior
 
-Redesign or explicitly justify:
+Code first.
 
-- `ObjectManager::get()` in feature code;
-- `$model->load()` / `$model->save()` in new code;
-- large observers;
-- business workflows in plugins;
-- `around` for simple argument/result changes;
-- preference for one public method;
-- copied core/vendor classes or unnecessary copied PHTML/JS;
-- repository/entity loads in large loops;
-- global cache flush after normal writes;
-- session/request state deep in business logic;
-- direct SQL bypassing required Magento lifecycle;
-- UI Components for every Admin page;
-- direct edits under `vendor/`.
+Prefer a patch/small implementation over an architecture essay.
 
-## Final Review
+After code, explain only what matters:
 
-Before finalizing an implementation, verify:
+```text
+Changed X.
+Skipped Y because Magento already handles it.
+Run Z only if this change affects ...
+```
 
-1. Is there already an XML/declarative solution?
-2. Is there a public API or narrower documented extension point?
-3. Am I replacing more code than necessary?
-4. Am I relying on non-public internals?
-5. Could composition replace inheritance/preference?
-6. Is `around` truly required?
-7. Is business logic trapped in a plugin/observer/resolver/controller?
-8. Is the data-access method appropriate, or merely habitual?
-9. Can this create N+1 queries?
-10. Does request/session state leak into reusable services?
-11. Is it correct under FPC, indexers/MView, retries, concurrency, and production DI compilation?
-12. Are ACL, ownership, escaping, SQL bindings, and CSRF correct?
-13. Will it survive the next Magento/vendor patch update?
+When multiple solutions work, choose the shortest robust one.
 
-For production-sensitive changes, validate relevant paths with `setup:di:compile`, production mode, static content deployment where applicable, cache/indexer modes, cron/consumers, and Magento Coding Standard checks.
+Do not present five architectural alternatives unless the user asks.
 
-## MerchantDuo Magento 2.4 session workflow
+## Ponytail intensity
 
-# Magento 2.4
+**lite**
+Implement what was requested, but mention a simpler Magento-native alternative
+if one obviously exists.
 
-Confirm the installed Magento version, edition, and deployment mode before changing framework behavior. Prefer a focused module, declarative schema and data patches, dependency injection, service contracts, layout XML, and Magento CLI validation. Do not read `app/etc/env.php`.
+**full**
+Default. Smallest safe Magento-native diff. No speculative architecture.
 
-Inspect the changed module and files before proposing post-change operations. Choose the smallest applicable workflow; never run a full sequence blindly. Ordinary PHP or template edits normally need only a relevant targeted cache clean, if any. Module registration, schema, declarative configuration, or dependency changes require `setup:upgrade` and the mode matrix below:
+**ultra**
+Challenge unnecessary requirements, delete before adding, and choose the
+smallest production-safe solution possible.
 
-| Detected mode | Post-change guidance |
-| --- | --- |
-| Developer | Run `setup:upgrade`, then clean only relevant cache types. Do not normally compile DI or deploy static content. |
-| Default | Run `setup:upgrade`, then clean only relevant cache types. Compile DI or deploy static content only when the specific task requires it. |
-| Production | Run maintenance enable → `setup:upgrade` → DI compile → static-content deploy → targeted cache clean → maintenance disable. |
+Ponytail never means skipping investigation.
 
-If the snapshot mode is unknown, report that rather than guessing a deployment sequence. Maintenance mode is recommended only for production module changes. Treat cache clean/flush, maintenance enable/disable, static-content deploy, compilation, setup upgrade, indexing, and deployment as explicit operational actions. Use `magento_workflow` rather than raw operational commands. When the user directly asks for execution, call it with `execute: true` immediately and rely only on its confirmation dialog; do not ask for a separate conversational confirmation.
+**Read the real flow first. Then be lazy.**