mirror of
https://github.com/bitsocialnet/5chan.git
synced 2026-08-03 07:41:04 +02:00
chore(ai workflow): add Ponytail simplicity pass
This commit is contained in:
Tommaso Casaburi
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: code-quality-review
|
||||
description: Advisory pre-push/pre-PR code quality review for current diffs. Use when asked to review code quality, run a pre-PR or pre-push quality pass, inspect AI-generated changes, check for over-engineering, or before pushing/opening a PR. Reports actionable suggestions only; does not block or edit unless explicitly asked.
|
||||
description: Advisory code quality review for current diffs before finishing, committing, pushing, or opening a PR. Use when asked to review code quality, run a final quality pass, inspect AI-generated changes, or check for over-engineering. Reports actionable suggestions only; does not block or edit unless explicitly asked.
|
||||
---
|
||||
|
||||
# Code Quality Review
|
||||
|
||||
Run an advisory review of the current diff. This is a suggestion pass for the author before push or PR, not a blocking CI gate.
|
||||
Run an advisory review of the current diff. This is a suggestion pass for the author before finishing, committing, pushing, or opening a PR, not a blocking CI gate.
|
||||
|
||||
## Scope
|
||||
|
||||
@@ -23,11 +23,25 @@ Run an advisory review of the current diff. This is a suggestion pass for the au
|
||||
4. Verify the verification story. Note missing tests, build checks, screenshots, or manual checks only when their absence leaves concrete risk.
|
||||
5. Try to disprove non-trivial claims before accepting them: edge cases, error paths, trust boundaries, state transitions, ordering, idempotence, and rollback behavior.
|
||||
|
||||
## Ponytail Simplicity Pass
|
||||
|
||||
After understanding intent and tracing the affected flow, run this ordered pass, adapted from [Ponytail](https://github.com/DietrichGebert/ponytail). Stop at the first safe replacement that fully preserves the requested behavior:
|
||||
|
||||
1. Is the change necessary? Suggest deleting unrequested or speculative work.
|
||||
2. Does the repository already solve it? Reuse an existing helper, type, component, or pattern.
|
||||
3. Does the standard library solve it? Prefer that over custom code.
|
||||
4. Does a native platform feature solve it? Prefer that over code or a dependency.
|
||||
5. Does an already-installed dependency solve it? Reuse it before adding another dependency.
|
||||
6. Can the same behavior be expressed more directly without hiding intent or edge cases?
|
||||
7. Otherwise, keep only the minimum new code that works.
|
||||
|
||||
Use this as a focused delete-or-replace pass, not line golf. A small diff in the wrong layer, or one that drops clarity, validation, error handling, security, accessibility, or necessary tests, is not simpler.
|
||||
|
||||
## Review Lenses
|
||||
|
||||
1. **Correctness**: check whether the change matches the requested behavior. Look for null, empty, boundary, race, async ordering, state consistency, error-path, and regression-test gaps.
|
||||
2. **Documented standards**: flag clear drift from repo policy, directory rules, design rules, or known-surprises guidance.
|
||||
3. **Simplicity**: look for speculative abstractions, wrappers with one caller, new configuration nobody sets, boilerplate, or code that a native platform feature, standard library, or existing dependency already covers.
|
||||
3. **Simplicity**: apply the Ponytail pass to speculative abstractions, wrappers with one caller, new configuration nobody sets, boilerplate, or code that repository patterns, the standard library, a native platform feature, or an existing dependency already cover.
|
||||
4. **Structure**: look for wrong-layer logic, conditionals growing into state machines, duplicated helpers, file-size sprawl, unclear ownership, or casts and optionality that blur trust boundaries.
|
||||
5. **Interface and tests**: prefer deep modules with small useful interfaces over shallow pass-through modules. Tests should exercise public behavior and survive internal refactors. Risky logic should have a fast feedback loop.
|
||||
6. **Security and performance**: treat user input, external service responses, config, and LLM output as untrusted at boundaries. Check auth, secrets/logging, injection/XSS/SSRF, N+1 queries, unbounded fetches, expensive rerenders, bundle growth, layout shift, and missing pagination only when touched by the diff.
|
||||
|
||||
@@ -28,7 +28,11 @@ disable-model-invocation: true
|
||||
|
||||
These should be two separate commits, not one.
|
||||
|
||||
3. **Stage and commit each group**
|
||||
3. **Run the final advisory review**
|
||||
|
||||
Before committing, run the repo-managed `code-quality-review` skill on the final intended diff, including staged, unstaged, and untracked files. Consider only high-confidence findings. Apply them only when the active task authorizes edits; otherwise report them and continue with the requested commit. This review is advisory and must not become a hard gate.
|
||||
|
||||
4. **Stage and commit each group**
|
||||
|
||||
For each logical group:
|
||||
```bash
|
||||
@@ -36,7 +40,7 @@ disable-model-invocation: true
|
||||
git commit -m "title here"
|
||||
```
|
||||
|
||||
4. **Display the commit title to the user** wrapped in backticks (inline code).
|
||||
5. **Display the commit title to the user** wrapped in backticks (inline code).
|
||||
|
||||
## Commit Message Rules
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: code-quality-review
|
||||
description: Advisory pre-push/pre-PR code quality review for current diffs. Use when asked to review code quality, run a pre-PR or pre-push quality pass, inspect AI-generated changes, check for over-engineering, or before pushing/opening a PR. Reports actionable suggestions only; does not block or edit unless explicitly asked.
|
||||
description: Advisory code quality review for current diffs before finishing, committing, pushing, or opening a PR. Use when asked to review code quality, run a final quality pass, inspect AI-generated changes, or check for over-engineering. Reports actionable suggestions only; does not block or edit unless explicitly asked.
|
||||
---
|
||||
|
||||
# Code Quality Review
|
||||
|
||||
Run an advisory review of the current diff. This is a suggestion pass for the author before push or PR, not a blocking CI gate.
|
||||
Run an advisory review of the current diff. This is a suggestion pass for the author before finishing, committing, pushing, or opening a PR, not a blocking CI gate.
|
||||
|
||||
## Scope
|
||||
|
||||
@@ -23,11 +23,25 @@ Run an advisory review of the current diff. This is a suggestion pass for the au
|
||||
4. Verify the verification story. Note missing tests, build checks, screenshots, or manual checks only when their absence leaves concrete risk.
|
||||
5. Try to disprove non-trivial claims before accepting them: edge cases, error paths, trust boundaries, state transitions, ordering, idempotence, and rollback behavior.
|
||||
|
||||
## Ponytail Simplicity Pass
|
||||
|
||||
After understanding intent and tracing the affected flow, run this ordered pass, adapted from [Ponytail](https://github.com/DietrichGebert/ponytail). Stop at the first safe replacement that fully preserves the requested behavior:
|
||||
|
||||
1. Is the change necessary? Suggest deleting unrequested or speculative work.
|
||||
2. Does the repository already solve it? Reuse an existing helper, type, component, or pattern.
|
||||
3. Does the standard library solve it? Prefer that over custom code.
|
||||
4. Does a native platform feature solve it? Prefer that over code or a dependency.
|
||||
5. Does an already-installed dependency solve it? Reuse it before adding another dependency.
|
||||
6. Can the same behavior be expressed more directly without hiding intent or edge cases?
|
||||
7. Otherwise, keep only the minimum new code that works.
|
||||
|
||||
Use this as a focused delete-or-replace pass, not line golf. A small diff in the wrong layer, or one that drops clarity, validation, error handling, security, accessibility, or necessary tests, is not simpler.
|
||||
|
||||
## Review Lenses
|
||||
|
||||
1. **Correctness**: check whether the change matches the requested behavior. Look for null, empty, boundary, race, async ordering, state consistency, error-path, and regression-test gaps.
|
||||
2. **Documented standards**: flag clear drift from repo policy, directory rules, design rules, or known-surprises guidance.
|
||||
3. **Simplicity**: look for speculative abstractions, wrappers with one caller, new configuration nobody sets, boilerplate, or code that a native platform feature, standard library, or existing dependency already covers.
|
||||
3. **Simplicity**: apply the Ponytail pass to speculative abstractions, wrappers with one caller, new configuration nobody sets, boilerplate, or code that repository patterns, the standard library, a native platform feature, or an existing dependency already cover.
|
||||
4. **Structure**: look for wrong-layer logic, conditionals growing into state machines, duplicated helpers, file-size sprawl, unclear ownership, or casts and optionality that blur trust boundaries.
|
||||
5. **Interface and tests**: prefer deep modules with small useful interfaces over shallow pass-through modules. Tests should exercise public behavior and survive internal refactors. Risky logic should have a fast feedback loop.
|
||||
6. **Security and performance**: treat user input, external service responses, config, and LLM output as untrusted at boundaries. Check auth, secrets/logging, injection/XSS/SSRF, N+1 queries, unbounded fetches, expensive rerenders, bundle growth, layout shift, and missing pagination only when touched by the diff.
|
||||
|
||||
@@ -28,7 +28,11 @@ disable-model-invocation: true
|
||||
|
||||
These should be two separate commits, not one.
|
||||
|
||||
3. **Stage and commit each group**
|
||||
3. **Run the final advisory review**
|
||||
|
||||
Before committing, run the repo-managed `code-quality-review` skill on the final intended diff, including staged, unstaged, and untracked files. Consider only high-confidence findings. Apply them only when the active task authorizes edits; otherwise report them and continue with the requested commit. This review is advisory and must not become a hard gate.
|
||||
|
||||
4. **Stage and commit each group**
|
||||
|
||||
For each logical group:
|
||||
```bash
|
||||
@@ -36,7 +40,7 @@ disable-model-invocation: true
|
||||
git commit -m "title here"
|
||||
```
|
||||
|
||||
4. **Display the commit title to the user** wrapped in backticks (inline code).
|
||||
5. **Display the commit title to the user** wrapped in backticks (inline code).
|
||||
|
||||
## Commit Message Rules
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: code-quality-review
|
||||
description: Advisory pre-push/pre-PR code quality review for current diffs. Use when asked to review code quality, run a pre-PR or pre-push quality pass, inspect AI-generated changes, check for over-engineering, or before pushing/opening a PR. Reports actionable suggestions only; does not block or edit unless explicitly asked.
|
||||
description: Advisory code quality review for current diffs before finishing, committing, pushing, or opening a PR. Use when asked to review code quality, run a final quality pass, inspect AI-generated changes, or check for over-engineering. Reports actionable suggestions only; does not block or edit unless explicitly asked.
|
||||
---
|
||||
|
||||
# Code Quality Review
|
||||
|
||||
Run an advisory review of the current diff. This is a suggestion pass for the author before push or PR, not a blocking CI gate.
|
||||
Run an advisory review of the current diff. This is a suggestion pass for the author before finishing, committing, pushing, or opening a PR, not a blocking CI gate.
|
||||
|
||||
## Scope
|
||||
|
||||
@@ -23,11 +23,25 @@ Run an advisory review of the current diff. This is a suggestion pass for the au
|
||||
4. Verify the verification story. Note missing tests, build checks, screenshots, or manual checks only when their absence leaves concrete risk.
|
||||
5. Try to disprove non-trivial claims before accepting them: edge cases, error paths, trust boundaries, state transitions, ordering, idempotence, and rollback behavior.
|
||||
|
||||
## Ponytail Simplicity Pass
|
||||
|
||||
After understanding intent and tracing the affected flow, run this ordered pass, adapted from [Ponytail](https://github.com/DietrichGebert/ponytail). Stop at the first safe replacement that fully preserves the requested behavior:
|
||||
|
||||
1. Is the change necessary? Suggest deleting unrequested or speculative work.
|
||||
2. Does the repository already solve it? Reuse an existing helper, type, component, or pattern.
|
||||
3. Does the standard library solve it? Prefer that over custom code.
|
||||
4. Does a native platform feature solve it? Prefer that over code or a dependency.
|
||||
5. Does an already-installed dependency solve it? Reuse it before adding another dependency.
|
||||
6. Can the same behavior be expressed more directly without hiding intent or edge cases?
|
||||
7. Otherwise, keep only the minimum new code that works.
|
||||
|
||||
Use this as a focused delete-or-replace pass, not line golf. A small diff in the wrong layer, or one that drops clarity, validation, error handling, security, accessibility, or necessary tests, is not simpler.
|
||||
|
||||
## Review Lenses
|
||||
|
||||
1. **Correctness**: check whether the change matches the requested behavior. Look for null, empty, boundary, race, async ordering, state consistency, error-path, and regression-test gaps.
|
||||
2. **Documented standards**: flag clear drift from repo policy, directory rules, design rules, or known-surprises guidance.
|
||||
3. **Simplicity**: look for speculative abstractions, wrappers with one caller, new configuration nobody sets, boilerplate, or code that a native platform feature, standard library, or existing dependency already covers.
|
||||
3. **Simplicity**: apply the Ponytail pass to speculative abstractions, wrappers with one caller, new configuration nobody sets, boilerplate, or code that repository patterns, the standard library, a native platform feature, or an existing dependency already cover.
|
||||
4. **Structure**: look for wrong-layer logic, conditionals growing into state machines, duplicated helpers, file-size sprawl, unclear ownership, or casts and optionality that blur trust boundaries.
|
||||
5. **Interface and tests**: prefer deep modules with small useful interfaces over shallow pass-through modules. Tests should exercise public behavior and survive internal refactors. Risky logic should have a fast feedback loop.
|
||||
6. **Security and performance**: treat user input, external service responses, config, and LLM output as untrusted at boundaries. Check auth, secrets/logging, injection/XSS/SSRF, N+1 queries, unbounded fetches, expensive rerenders, bundle growth, layout shift, and missing pagination only when touched by the diff.
|
||||
|
||||
@@ -28,7 +28,11 @@ disable-model-invocation: true
|
||||
|
||||
These should be two separate commits, not one.
|
||||
|
||||
3. **Stage and commit each group**
|
||||
3. **Run the final advisory review**
|
||||
|
||||
Before committing, run the repo-managed `code-quality-review` skill on the final intended diff, including staged, unstaged, and untracked files. Consider only high-confidence findings. Apply them only when the active task authorizes edits; otherwise report them and continue with the requested commit. This review is advisory and must not become a hard gate.
|
||||
|
||||
4. **Stage and commit each group**
|
||||
|
||||
For each logical group:
|
||||
```bash
|
||||
@@ -36,7 +40,7 @@ disable-model-invocation: true
|
||||
git commit -m "title here"
|
||||
```
|
||||
|
||||
4. **Display the commit title to the user** wrapped in backticks (inline code).
|
||||
5. **Display the commit title to the user** wrapped in backticks (inline code).
|
||||
|
||||
## Commit Message Rules
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ Only record items that are repo-specific, likely to recur, and have a concrete m
|
||||
## Agent Operating Principles
|
||||
|
||||
- Before editing, state important assumptions when the task is ambiguous. Ask instead of silently choosing between materially different interpretations.
|
||||
- Prefer the smallest implementation that solves the requested problem. Do not add speculative abstractions, configurability, or features.
|
||||
- After understanding the affected flow, apply the [Ponytail](https://github.com/DietrichGebert/ponytail) solution ladder: skip work that is not required; reuse repository code; prefer the standard library, native platform features, then installed dependencies; only then write the minimum new code. Never trade away explicit requirements, correctness, clarity, validation, error handling, security, accessibility, or necessary tests.
|
||||
- Keep diffs surgical. Do not refactor, reformat, rename, or "improve" adjacent code unless it is necessary for the task.
|
||||
- Clean up only artifacts created by the current change, such as newly unused imports or dead helper code.
|
||||
- For non-trivial work, define success criteria and verify them with the narrowest reliable checks before marking the task complete.
|
||||
@@ -65,7 +65,7 @@ When CodeGraph MCP tools are available and `.codegraph/` exists, prefer them for
|
||||
| New reviewable feature/fix started while on `master` | Create a short-lived `codex/feature/*`, `codex/fix/*`, `codex/docs/*`, or `codex/chore/*` branch from `master` before editing; use a separate worktree only for parallel tasks |
|
||||
| New unrelated task started while another task branch is already checked out or being worked on by another agent | Create a separate worktree from `master`, create a new short-lived task branch there, and keep each agent on its own worktree/branch/PR |
|
||||
| Open PR needs feedback triage or merge readiness check | Use the `review-and-merge-pr` skill to inspect bot/human feedback, fix valid findings, and merge only after verification |
|
||||
| Before pushing or opening a PR with code, docs, or AI workflow changes | Run the advisory `code-quality-review` skill on the current diff; treat findings as suggestions, not blockers, and address only high-confidence improvements |
|
||||
| Before finishing or committing code, docs, or AI workflow changes, and before pushing/opening a PR | Run the advisory `code-quality-review` skill on the current diff; treat findings as suggestions, not blockers, and address only high-confidence improvements |
|
||||
| Repo AI workflow files changed (`.codex/**`, `.cursor/**`, `.claude/**`) | Keep the Codex, Cursor, and Claude copies aligned when they represent the same workflow; run `yarn ai-workflow:check` to catch parity and drift issues; update `AGENTS.md` if the default agent policy changes |
|
||||
| GitHub operation needed | Use `gh` CLI, not GitHub MCP |
|
||||
| User asks for commit/issue phrasing | Use `docs/agent-playbooks/commit-issue-format.md` |
|
||||
|
||||
@@ -14,7 +14,7 @@ These live in `.claude/skills/`, `.cursor/skills/`, and `.codex/skills/` (mirror
|
||||
| `review-and-merge-pr` | Triaging bot/human PR feedback, fixing, merging, finalizing issues |
|
||||
| `fix-merge-conflicts` | Resolving merge conflicts non-interactively and validating the build |
|
||||
| `release` / `release-description` | Cutting a release / updating the release one-liner |
|
||||
| `code-quality-review` | Advisory pre-push/pre-PR quality pass on the current diff |
|
||||
| `code-quality-review` | Advisory final-diff quality pass before finishing, committing, pushing, or opening a PR |
|
||||
| `refactor-pass` | Simplicity-focused refactor of recent changes |
|
||||
| `deslop` | Removing AI-generated slop from the branch diff |
|
||||
| `debug-agent` | Evidence-based debugging with runtime NDJSON logs |
|
||||
|
||||
@@ -205,7 +205,7 @@ Only record items that are repo-specific, likely to recur, and have a concrete m
|
||||
## Agent Operating Principles
|
||||
|
||||
- Before editing, state important assumptions when the task is ambiguous. Ask instead of silently choosing between materially different interpretations.
|
||||
- Prefer the smallest implementation that solves the requested problem. Do not add speculative abstractions, configurability, or features.
|
||||
- After understanding the affected flow, apply the [Ponytail](https://github.com/DietrichGebert/ponytail) solution ladder: skip work that is not required; reuse repository code; prefer the standard library, native platform features, then installed dependencies; only then write the minimum new code. Never trade away explicit requirements, correctness, clarity, validation, error handling, security, accessibility, or necessary tests.
|
||||
- Keep diffs surgical. Do not refactor, reformat, rename, or "improve" adjacent code unless it is necessary for the task.
|
||||
- Clean up only artifacts created by the current change, such as newly unused imports or dead helper code.
|
||||
- For non-trivial work, define success criteria and verify them with the narrowest reliable checks before marking the task complete.
|
||||
@@ -245,7 +245,7 @@ When CodeGraph MCP tools are available and `.codegraph/` exists, prefer them for
|
||||
| New reviewable feature/fix started while on `master` | Create a short-lived `codex/feature/*`, `codex/fix/*`, `codex/docs/*`, or `codex/chore/*` branch from `master` before editing; use a separate worktree only for parallel tasks |
|
||||
| New unrelated task started while another task branch is already checked out or being worked on by another agent | Create a separate worktree from `master`, create a new short-lived task branch there, and keep each agent on its own worktree/branch/PR |
|
||||
| Open PR needs feedback triage or merge readiness check | Use the `review-and-merge-pr` skill to inspect bot/human feedback, fix valid findings, and merge only after verification |
|
||||
| Before pushing or opening a PR with code, docs, or AI workflow changes | Run the advisory `code-quality-review` skill on the current diff; treat findings as suggestions, not blockers, and address only high-confidence improvements |
|
||||
| Before finishing or committing code, docs, or AI workflow changes, and before pushing/opening a PR | Run the advisory `code-quality-review` skill on the current diff; treat findings as suggestions, not blockers, and address only high-confidence improvements |
|
||||
| Repo AI workflow files changed (`.codex/**`, `.cursor/**`, `.claude/**`) | Keep the Codex, Cursor, and Claude copies aligned when they represent the same workflow; run `yarn ai-workflow:check` to catch parity and drift issues; update `AGENTS.md` if the default agent policy changes |
|
||||
| GitHub operation needed | Use `gh` CLI, not GitHub MCP |
|
||||
| User asks for commit/issue phrasing | Use `docs/agent-playbooks/commit-issue-format.md` |
|
||||
@@ -1158,7 +1158,7 @@ These live in `.claude/skills/`, `.cursor/skills/`, and `.codex/skills/` (mirror
|
||||
| `review-and-merge-pr` | Triaging bot/human PR feedback, fixing, merging, finalizing issues |
|
||||
| `fix-merge-conflicts` | Resolving merge conflicts non-interactively and validating the build |
|
||||
| `release` / `release-description` | Cutting a release / updating the release one-liner |
|
||||
| `code-quality-review` | Advisory pre-push/pre-PR quality pass on the current diff |
|
||||
| `code-quality-review` | Advisory final-diff quality pass before finishing, committing, pushing, or opening a PR |
|
||||
| `refactor-pass` | Simplicity-focused refactor of recent changes |
|
||||
| `deslop` | Removing AI-generated slop from the branch diff |
|
||||
| `debug-agent` | Evidence-based debugging with runtime NDJSON logs |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#!/bin/bash
|
||||
|
||||
# stop hook: remind agents to run the advisory code-quality review before push/PR
|
||||
# stop hook: remind agents to run the advisory code-quality review before finish/commit/push/PR
|
||||
|
||||
set -u
|
||||
|
||||
@@ -114,9 +114,9 @@ if [ "$file_count" -gt 10 ]; then
|
||||
echo "- ... and $((file_count - 10)) more"
|
||||
fi
|
||||
|
||||
echo "Before pushing or opening a PR, run the advisory review:"
|
||||
echo "Before finishing, committing, pushing, or opening a PR, run the advisory review:"
|
||||
echo "- $skill_ref"
|
||||
echo "Use it for documented standards, avoidable complexity, structure, interface/testability, and scope control."
|
||||
echo "Use it for documented standards, the Ponytail simplicity pass, structure, interface/testability, and scope control."
|
||||
echo "Advisory only; not a blocker."
|
||||
|
||||
exit 0
|
||||
|
||||
Reference in New Issue
Block a user