@mohammadhprp/system-prompt 0.12.4 → 0.12.5

package/framework/commands/review.md

@@ -1,24 +1,9 @@
 ---
-description: Perform comprehensive code quality review
+description: Review local, GitHub, or GitLab changes and write review.json
 agent: plan
 ---
 
-Review $ARGUMENTS
-
-Perform comprehensive code quality review.
-
-## Process
-
-1. **Review conversation and diff** - Read conversation history, run `git diff` for staged/unstaged changes, identify the problem being solved and the behavior being modified. Read related standards: [`references/standards/naming.md`](../references/standards/naming.md), [`references/standards/testing.md`](../references/standards/testing.md), [`references/standards/security.md`](../references/standards/security.md), [`references/standards/performance.md`](../references/standards/performance.md).
-
-2. **Check correctness** - Edge cases, concurrency, error handling, state transitions, backward compatibility. Read contracts and interfaces before implementation.
-
-3. **Check maintainability** - Naming reflects business meaning, structure matches project conventions, comments explain why not what.
-
-4. **Check testing** - Do tests prove the behavior change? Missing edge cases or failure paths? Tests should verify behavior, not mirror implementation.
-
-5. **Check performance** - N+1 queries, unbounded loops, unnecessary allocations, caching opportunities.
-
-6. **Check security** - Input validation, authentication enforcement, secrets exposure, least privilege.
-
-7. **Present findings** - Distinguish blockers from suggestions, explain reasoning for each, summarize overall risk and production readiness.
+Review `$ARGUMENTS` using the `review` skill. Select local changes, a GitHub
+pull request, or a GitLab merge request from the arguments. Use `gh` or `glab`
+for read-only remote inspection, never publish comments, and write the required
+`review.json` artifact.

package/framework/skills/gh/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: gh
+description: Expert guidance for using the GitHub CLI (gh) to work with repositories, issues, pull requests, Actions, releases, and the GitHub API from the command line. Use this skill whenever the user needs to perform a GitHub workflow or asks to use gh.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# GitHub CLI (`gh`) Skill
+
+Use the official `gh` CLI for GitHub operations instead of manually constructing API requests or browser workflows when a supported command exists.
+
+## When to Use This Skill
+
+Invoke when the user needs to:
+
+- Inspect, create, edit, review, merge, or close pull requests
+- Search, create, edit, comment on, or close issues
+- Inspect repositories, branches, releases, tags, or notifications
+- View, rerun, cancel, or inspect logs for GitHub Actions workflows
+- Create and manage releases
+- Query or mutate GitHub resources through the API
+
+## Prerequisites and Authentication
+
+Verify that the CLI is installed before executing commands:
+
+```bash
+gh --version
+```
+
+Check the active account and token scopes:
+
+```bash
+gh auth status
+```
+
+If authentication is missing, use the interactive login flow:
+
+```bash
+gh auth login
+```
+
+For automation, prefer a short-lived `GH_TOKEN` or `GITHUB_TOKEN` environment variable. Never print, commit, or include token values in command output, issue bodies, pull requests, or logs.
+
+## Repository Context
+
+Most commands infer the repository from the current Git remote. Confirm context when it matters:
+
+```bash
+git remote -v
+gh repo view --json nameWithOwner,defaultBranchRef
+```
+
+Use `--repo OWNER/REPO` when running outside a checkout or targeting another repository.
+
+## Core Workflows
+
+### Pull Requests
+
+```bash
+# List and inspect PRs
+gh pr list --state open
+gh pr view 123 --comments
+
+# Create a PR after pushing the branch
+git push -u origin HEAD
+gh pr create --base main --title "Add feature" --body "Summary and testing notes"
+
+# Review a PR
+gh pr checkout 123
+gh pr diff 123
+gh pr review 123 --approve
+
+# Merge only after the user has explicitly approved the merge
+gh pr merge 123 --squash --delete-branch
+```
+
+Prefer `--body-file` for substantial descriptions and `--json` with `--jq` for reliable scripting. Before creating or updating a PR, inspect repository templates and existing branch commits when the workflow requires them.
+
+### Issues
+
+```bash
+gh issue list --state open --assignee @me
+gh issue view 123 --comments
+gh issue create --title "Bug report" --body-file bug.md --label bug
+gh issue comment 123 --body "Investigation is complete."
+```
+
+Use `--repo OWNER/REPO` for issues in another repository. Treat closing, reopening, editing, and deleting issues as mutating operations that require clear user intent.
+
+### GitHub Actions
+
+```bash
+gh run list --limit 20
+gh run view RUN_ID
+gh run view RUN_ID --log-failed
+gh run watch RUN_ID
+gh workflow run workflow.yml --ref main
+```
+
+Confirm the workflow name, ref, and inputs before dispatching a workflow. Do not rerun or cancel runs without user authorization.
+
+### Releases and Repositories
+
+```bash
+gh release list
+gh release view v1.2.3
+gh release create v1.2.3 --generate-notes
+gh repo view OWNER/REPO
+gh repo clone OWNER/REPO
+```
+
+Creating, editing, or deleting releases and repositories is destructive or externally visible; confirm the target and requested changes first.
+
+## API and Scripting
+
+Use structured output rather than parsing human-readable tables:
+
+```bash
+gh pr list --json number,title,state --jq '.[] | [.number, .title, .state] | @tsv'
+gh api repos/OWNER/REPO/issues --paginate --jq '.[] | [.number, .title] | @tsv'
+```
+
+For API mutations, state the HTTP method and target before execution and ask for confirmation when the operation changes remote data:
+
+```bash
+gh api repos/OWNER/REPO/issues --method POST \
+  -f title='Bug report' -f body='Details'
+```
+
+Use `gh <command> --help` and `gh api --help` when exact flags or endpoint behavior is uncertain. Prefer `--paginate` for collection endpoints and constrain fields with `--jq` to avoid exposing unnecessary data.
+
+## Best Practices
+
+1. Run `gh auth status` before diagnosing authentication failures.
+2. Check `git status`, the current branch, and the remote before PR or release work.
+3. Use `--repo OWNER/REPO` rather than changing directories solely to select a repository.
+4. Use `--json`/`--jq` for scripts and `--body-file` for multiline content.
+5. Confirm before pushing, merging, closing, deleting, dispatching, rerunning, or cancelling remote work.
+6. Do not bypass branch protection or approval requirements unless the user explicitly requests it and has authority.
+
+## Common Problems
+
+- **`gh: command not found`** — Install GitHub CLI and verify it is on `PATH`.
+- **Authentication or scope errors** — Run `gh auth status`, then `gh auth refresh` or `gh auth login` as appropriate.
+- **Wrong repository** — Check `git remote -v` and pass `--repo OWNER/REPO` explicitly.
+- **PR cannot merge** — Inspect `gh pr checks NUMBER`, mergeability, required reviews, and branch protection.
+- **Workflow dispatch fails** — Confirm the workflow supports `workflow_dispatch`, the ref exists, and required inputs are supplied.
+- **API returns 404** — Verify repository spelling and that the authenticated account can access it.
+
+## Quick Reference
+
+- `gh repo view` — View the current repository
+- `gh pr list` / `gh pr view NUMBER` / `gh pr create` — Pull request workflows
+- `gh issue list` / `gh issue view NUMBER` / `gh issue create` — Issue workflows
+- `gh run list` / `gh run view ID` / `gh run watch ID` — Actions workflows
+- `gh release list` / `gh release create TAG` — Release workflows
+- `gh api ENDPOINT` — GitHub REST or GraphQL API access

package/framework/skills/gh/examples.md

@@ -0,0 +1,10 @@
+# Examples
+
+- Check `gh auth status` and repository context before performing GitHub operations.
+- List open pull requests, inspect a specific PR with comments and checks, and summarize its status without changing remote data.
+- Prepare a pull request from the current branch by reviewing commits and templates, then show the proposed title and body before creating it.
+- Search issues with structured `--json` and `--jq` output, avoiding fragile parsing of terminal tables.
+- Inspect a failed GitHub Actions run with `gh run view RUN_ID --log-failed` and summarize the relevant failure.
+- Create or dispatch a workflow only after confirming the workflow, ref, and inputs with the user.
+- Use `gh api` for an endpoint not covered by a subcommand, preferring read-only requests and requesting confirmation before mutations.
+- Ask for explicit confirmation before pushing, merging, closing, deleting, rerunning, cancelling, or publishing remote resources.

package/framework/skills/ponytail/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: ponytail
+description: >
+  Apply the ponytail workflow to coding, implementation, refactoring, design,
+  dependency choices, and over-engineering reviews. Use whenever the user says
+  "ponytail", "be lazy", "lazy mode", "simplest solution", "minimal solution",
+  "YAGNI", "do less", "shortest path", "what can I delete", "find bloat", or
+  asks for a ponytail review, audit, debt ledger, gain scoreboard, or help
+  reference. This single skill replaces the former ponytail commands and
+  companion skills; select the requested operation from its references. Do not
+  use for non-coding requests such as general knowledge, prose, translation,
+  summaries, or recipes.
+argument-hint: "[lite|full|ultra]"
+license: MIT
+---
+
+# Ponytail
+
+This is the only ponytail skill. Former commands (`/ponytail`,
+`/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`, `/ponytail-gain`, and
+`/ponytail-help`) are operation aliases handled here. Read only the matching
+reference when an alias is requested:
+
+| Operation | Reference |
+|---|---|
+| Build or refactor with ponytail | `references/ponytail-mode.md` |
+| Review current changes | `references/ponytail-review.md` |
+| Audit the whole repository | `references/ponytail-audit.md` |
+| Harvest `ponytail:` comments | `references/ponytail-debt.md` |
+| Show measured impact | `references/ponytail-gain.md` |
+| Show the quick reference | `references/ponytail-help.md` |
+| Load the compact rule card | `references/ponytail-rules.md` |
+
+Project principles are also references, not standalone skills:
+
+`references/principle-boundary-discipline.md`,
+`references/principle-encode-lessons-in-structure.md`,
+`references/principle-fix-root-causes.md`,
+`references/principle-make-operations-idempotent.md`,
+`references/principle-model-the-domain.md`,
+`references/principle-prove-it-works.md`, and
+`references/principle-sequence-verifiable-units.md`.
+
+If the user invokes a former slash command, follow the corresponding reference
+and do not treat it as a separate skill.
+
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
+unsure. Off only: "stop ponytail" / "normal mode". Default: **full**.
+Switch: `/ponytail lite|full|ultra`.
+
+## The ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
+5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+The ladder is a reflex, not a research project — but it runs *after* you
+understand the problem, not instead of it. Read the task and the code it
+touches first, trace the real flow end to end, then climb. Two rungs work →
+take the higher one and move on. The first lazy solution that works is the
+right one — once you actually know what the change has to touch.
+
+**Bug fix = root cause, not symptom.** A report names a symptom. Before you
+edit, grep every caller of the function you're about to touch. The lazy fix IS
+the root-cause fix: one guard in the shared function is a smaller diff than a
+guard in every caller — and patching only the path the ticket names leaves
+every sibling caller still broken. Fix it once, where all callers route through.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate, no scaffolding "for later", later can scaffold for itself.
+- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
+- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
+- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path (`# ponytail: global lock, per-account locks if throughput matters`).
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it.
+No essays, no feature tours, no design notes. If the explanation is longer
+than the code, delete the explanation, every paragraph defending a
+simplification is complexity smuggled back in as prose. Explanation the user
+explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
+give it in full, the rule is only against unrequested prose.
+
+Pattern: `[code] → skipped: [X], add when [Y].`
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | Build what's asked, but name the lazier alternative in one line. User picks. |
+| **full** | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default. |
+| **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
+
+Example: "Add a cache for these API responses."
+- lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it, no
+re-arguing.
+
+Never lazy about understanding the problem. The ladder shortens the
+solution, never the reading. Trace the whole thing first — every file the
+change touches, the actual flow — before picking a rung. Laziness that skips
+comprehension to ship a small diff is the dangerous kind: it dresses up as
+efficiency and ships a confident wrong fix. Read fully, then be lazy.
+
+Hardware is never the ideal on paper: a real clock drifts, a real sensor
+reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not
+just less code, the physical world needs tuning a minimal model can't see.
+
+Lazy code without its check is unfinished. Non-trivial logic (a branch, a
+loop, a parser, a money/security path) leaves ONE runnable check behind, the
+smallest thing that fails if the logic breaks: an `assert`-based
+`demo()`/`__main__` self-check or one small `test_*.py`. No frameworks, no
+fixtures, no per-function suites unless asked. Trivial one-liners need no
+test, YAGNI applies to tests too.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk (pair with Caveman for
+terse prose). "stop ponytail" / "normal mode": revert. Level persists until
+changed or session end.
+
+The shortest path to done is the right path.

package/framework/skills/ponytail/references/ponytail-audit.md

@@ -0,0 +1,18 @@
+# Ponytail audit
+
+Use for `/ponytail-audit` or a request to audit the whole repository for
+over-engineering. Scan the whole tree, not only the current diff. Do not apply
+fixes. Rank findings from the biggest cut first.
+
+Use the review tags and hunt for standard-library or platform replacements,
+single-implementation interfaces, one-product factories, delegating wrappers,
+single-export files, dead flags or configuration, and hand-rolled standard
+library behavior.
+
+Report one finding per line:
+
+`<tag> <what to cut>. <replacement>. [path]`
+
+End with `net: -<N> lines, -<M> deps possible.` If nothing can be removed, say
+`Lean already. Ship.` Scope is complexity only; do not report correctness,
+security, or performance issues.

package/framework/skills/ponytail/references/ponytail-debt.md

@@ -0,0 +1,21 @@
+# Ponytail debt
+
+Use for `/ponytail-debt`, “what did ponytail defer”, or a request for the
+shortcut ledger. Read and report only unless the user explicitly asks to write
+the ledger to a file.
+
+Search the repository for comment markers while skipping `node_modules`,
+`.git`, and build output:
+
+```bash
+grep -rnE '(#|//) ?ponytail:' .
+```
+
+Treat each hit as one row, grouped by file:
+
+`<file>:<line>, <what was simplified>. ceiling: <limit>. upgrade: <trigger>.`
+
+Extract the ceiling and upgrade trigger from the comment. Mark entries with no
+upgrade path or trigger as `no-trigger`. End with
+`<N> markers, <M> with no trigger.` If there are no hits, say
+`No ponytail: debt. Clean ledger.`

package/framework/skills/ponytail/references/ponytail-gain.md

@@ -0,0 +1,25 @@
+# Ponytail gain
+
+Use for `/ponytail-gain`, “what does ponytail save”, or a request for the
+measured-impact scoreboard. This is a one-shot display: do not change mode,
+write files, or persist anything.
+
+Render these published benchmark medians as plain ASCII bars (five everyday
+tasks and the Haiku, Sonnet, and Opus models):
+
+```text
+  ponytail gain                     benchmark median · 5 tasks · 3 models
+
+  Lines of code   no-skill  ████████████████████  100%
+                  ponytail  ██▌·················    6–20%   ▼ 80–94%
+  Cost            no-skill  ████████████████████  100%
+                  ponytail  █████▌··············   23–53%  ▼ 47–77%
+  Speed           ponytail  ▸ 3–6× faster
+
+  This repo:  /ponytail-debt  (shortcuts you deferred)
+              /ponytail-audit (what's still cuttable)
+```
+
+These are benchmark figures, not this repository. Never invent a per-repo
+savings number; the only real repo figures come from the counted debt ledger
+and audit.

package/framework/skills/ponytail/references/ponytail-help.md

@@ -0,0 +1,18 @@
+# Ponytail help
+
+Use for `/ponytail-help`, “ponytail help”, or a request for the quick
+reference. Display it once without changing mode, writing files, or persisting
+anything.
+
+| Operation | Trigger | Purpose |
+|---|---|---|
+| Mode | `/ponytail [lite\|full\|ultra\|off]` | Build the simplest solution that works. |
+| Review | `/ponytail-review` | Find removable complexity in current changes. |
+| Audit | `/ponytail-audit` | Find removable complexity across the repository. |
+| Debt | `/ponytail-debt` | Harvest `ponytail:` comments into a ledger. |
+| Gain | `/ponytail-gain` | Show benchmark medians, not repo savings. |
+| Help | `/ponytail-help` | Show this card. |
+
+Say `stop ponytail` or `normal mode` to deactivate. Resume with `/ponytail`.
+The default is `full`; configure it with `PONYTAIL_DEFAULT_MODE` or
+`~/.config/ponytail/config.json` as described in `references/ponytail-mode.md`.

package/framework/skills/ponytail/references/ponytail-mode.md

@@ -0,0 +1,33 @@
+# Ponytail mode
+
+Use this operation for `/ponytail`, `/ponytail lite`, `/ponytail full`,
+`/ponytail ultra`, or `/ponytail off`.
+
+Ponytail is active every response until the user says `stop ponytail`, `normal
+mode`, or `/ponytail off`. The default is **full**.
+
+## Levels
+
+| Level | Behavior |
+|---|---|
+| **lite** | Build what was asked, then name the lazier alternative in one line. |
+| **full** | Enforce the YAGNI → existing code → stdlib → native → installed dependency → one line → minimum ladder. Default. |
+| **ultra** | Delete before adding, challenge the requirement, and ship the smallest viable result. |
+
+Use the main skill's ladder and rules for the actual coding task. A mode switch
+does not itself change files or create configuration.
+
+## Configuration
+
+Default resolution is environment variable, then config file, then `full`:
+
+```bash
+export PONYTAIL_DEFAULT_MODE=ultra
+```
+
+Config file: `~/.config/ponytail/config.json` (Windows:
+`%APPDATA%\ponytail\config.json`).
+
+```json
+{ "defaultMode": "lite" }
+```

package/framework/skills/ponytail/references/ponytail-review.md

@@ -0,0 +1,27 @@
+# Ponytail review
+
+Use for `/ponytail-review` or a request to review changes for
+over-engineering. Review the current diff only. Do not apply fixes.
+
+Scope is complexity only; route correctness bugs, security holes, and
+performance issues to a normal review.
+
+Report one finding per line:
+
+`<file>:L<line>: <tag> <what to cut>. <replacement>.`
+
+Tags:
+
+- `delete:` dead code, unused flexibility, or speculative features; replacement
+  is nothing.
+- `stdlib:` hand-rolled functionality supplied by the standard library; name
+  the function.
+- `native:` a dependency or custom code doing what the platform already does;
+  name the native feature.
+- `yagni:` an abstraction with one implementation, unused configuration, or a
+  layer with one caller.
+- `shrink:` equivalent logic that can use fewer lines; show the shorter form.
+
+End with `net: -<N> lines possible.` If there is nothing to cut, say
+`Lean already. Ship.` Do not flag a single smoke test or assert-based
+self-check as bloat.

package/framework/skills/ponytail/references/ponytail-rules.md

@@ -0,0 +1,31 @@
+# Ponytail rules
+
+Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after understanding the problem, not instead of it. Read the
+task and touched code, trace the real flow end to end, then choose the rung.
+
+For bug fixes, find every caller of the function being changed and fix the
+shared root cause once. Do not scatter symptom guards across callers.
+
+Do not simplify away input validation at trust boundaries, error handling that
+prevents data loss, security, accessibility, hardware calibration, or anything
+explicitly requested. Non-trivial lazy code leaves one runnable check behind;
+trivial one-liners need no test.
+
+Mark deliberate shortcuts with a `ponytail:` comment naming the ceiling and
+upgrade path, for example:
+
+```text
+# ponytail: global lock, per-account locks if throughput matters
+```

package/framework/skills/ponytail/references/principle-boundary-discipline.md

@@ -0,0 +1,7 @@
+# Boundary Discipline
+
+Validate and normalize untrusted data at the boundary, then pass typed and validated values into internal domain code.
+
+Relevant boundaries include FormRequests, route parameters, Artisan arguments, environment configuration, uploaded files, database rows, HTTP responses, CSV or Excel imports, and tenant context. Use existing requests, enums, rules, scopes, and service abstractions.
+
+Do not accept `tenant_id` from untrusted Admin input when authenticated context determines the tenant. Do not repeat defensive validation throughout trusted internal call chains. Keep controllers and framework adapters thin; keep pricing, order, import, and state logic in the established services, actions, pipes, and domain structures.

package/framework/skills/ponytail/references/principle-encode-lessons-in-structure.md

@@ -0,0 +1,13 @@
+# Encode Lessons In Structure
+
+When a rule is repeated, ask whether it belongs in a mechanism rather than another instruction.
+
+Prefer the strongest practical enforcement:
+
+- A type, enum, or database constraint
+- An architecture or security test
+- A canonical helper, scope, policy, or service
+- A runtime guard at the correct boundary
+- A concise project skill when the rule still requires judgment
+
+Examples include enforcing tenant access through existing scopes and middleware, preventing forbidden debugging calls through architecture tests, using unique keys for imports, and centralizing API response envelopes. Do not add a textual reminder when a reliable structural check can prevent the mistake.

package/framework/skills/ponytail/references/principle-fix-root-causes.md

@@ -0,0 +1,17 @@
+# Fix Root Causes
+
+When debugging, do not paper over symptoms. Trace every problem to its root cause and fix it there.
+
+**Why:** Symptom fixes accumulate. Each workaround makes the system harder to reason about, and the real bug remains. Root-cause fixes are slower upfront but reduce total debugging time.
+
+**Pattern:**
+- Reproduce first (if you can't reproduce it, you can't verify your fix)
+- Ask "why" until you hit the root cause
+- Resist the urge to add guards (adding a nil check to silence a crash is a symptom fix)
+- If a workaround needs a paragraph-long comment to justify it, the code is wrong (fix the code, not the comment)
+- Check for the pattern, not just the instance (grep for the same pattern, fix all instances)
+- When stuck, instrument. Don't guess (add logging, read the actual error)
+
+**Restart bugs: suspect state before code**
+
+Code doesn't change between runs. State does. When something "fails after restart," suspect stale persistent state first: config files, caches, lock files, serialized state. If clearing a state file restores behavior, prioritize state validation as the fix.

package/framework/skills/ponytail/references/principle-make-operations-idempotent.md

@@ -0,0 +1,12 @@
+# Make Operations Idempotent
+
+Design state-changing operations so repeated execution converges to the same correct state. Before changing a command, job, importer, pipeline step, or integration, answer:
+
+- What happens if it runs twice?
+- What happens if it crashes after each state change?
+- What happens when Laravel retries the job?
+- Can duplicate records, stock changes, notifications, or external requests occur?
+
+Apply this especially to `app/Imports`, `app/Console/Commands`, `app/Jobs`, order pipes, stock actions, and Rahkaran or Elasticsearch synchronization.
+
+Prefer stable external identifiers, unique database constraints, upserts, transactions, checkpointed progress, and safe retry behavior. Preserve tenant isolation while reconciling partial work. Test a successful run twice and test the important crash or retry boundary when practical.

package/framework/skills/ponytail/references/principle-model-the-domain.md

@@ -0,0 +1,7 @@
+# Model the Domain
+
+Represent domain rules in structures that make invalid states difficult to create instead of spreading conditions across files.
+
+Prefer existing enums, state services, policies, value objects, typed request data, registries, scopes, and pipeline data. For Chideli, inspect `OrderStatusEnum`, `OrderItemStatusEnum`, `OrderStateService`, `OrderPipelineData`, pricing services, and sale policy types before adding branches.
+
+Do not introduce an abstraction only to move code. Add one when it removes duplicated rules, contradictory states, or repeated conditionals. Preserve the existing ownership boundary and cover each meaningful state transition with tests.

package/framework/skills/ponytail/references/principle-prove-it-works.md

@@ -0,0 +1,27 @@
+# Prove It Works
+
+Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles."
+
+**Why:** Unverified work has unknown correctness. Indirect verification (file mtimes, output freshness, agent self-reports, cached screenshots) feels cheaper than direct observation. Acting on a wrong inference costs far more than checking the source.
+
+**Pattern:** After completing any task, ask: "how do I prove this actually works?"
+
+Check the real thing, not a proxy:
+- Check process liveness directly, not indirectly through derived state
+- Read the actual value, not a cached or derived representation
+- When verification fails, suspect the observation method before suspecting the system
+
+Code and features:
+1. Build it (necessary but not sufficient)
+2. Run it and exercise the actual feature path
+3. Check the full chain: does data flow from input to output?
+4. For integrations, test the full communication path end-to-end
+
+Delegation: trust artifacts, not self-reports.
+When verifying delegated work, inspect the actual output artifact (git diff, file contents, runtime behavior), not the delegate's summary. Agents report what they intended, not always what happened.
+
+## Script the check when you can
+
+The strongest proof is a deterministic script that re-runs the same comparison, not a one-time eyeball. Write the script, run it, and keep its output as an artifact a reviewer can re-run instead of trusting your word. A script comparing the old and new compiled output catches what a glance misses.
+
+Keep the artifact visible for the human. Commit it only for large or complex work where the trail has to be auditable later, like a big port or migration (the **show-me-your-work** skill). Most work just needs it visible, not committed.

package/framework/skills/ponytail/references/principle-sequence-verifiable-units.md

@@ -0,0 +1,7 @@
+# Sequence Work Into Verifiable Units
+
+Break broad work into small units, and verify each unit before starting the next. A unit may be one migration, one endpoint, one importer change, or one focused refactor with its tests.
+
+Start from a known-good state. Make one change. Run the narrowest relevant check. Inspect the result. Then continue. Do not batch many edits and postpone all verification until the end.
+
+When commits are requested, order them so a reviewer can follow the proof: prerequisite or regression test, implementation, cleanup, and final verification. Preserve migration order and tenant safety at every step.