npm - @event4u/agent-config - Versions diffs - 1.16.0 → 1.18.0 - Mend

@event4u/agent-config 1.16.0 → 1.18.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.

Files changed (224) hide show

package/.agent-src/skills/requesting-code-review/SKILL.md CHANGED Viewed

@@ -11,17 +11,19 @@ source: package
 ## When to use
 * About to run `/create-pr` or `/prepare-for-review`
-* Feature or bug fix is code-complete and the next step is "get eyes on it"
-* A stacked PR is ready and the parent-branch reviewer needs to
+* A feature or bug fix is code-complete and the next step is "get
+  eyes on it"
+* A stacked PR is ready and you need the parent branch reviewer to
   context-switch smoothly
-* Asking a human for a quick sanity check on a specific commit or diff
+* Asking a human for a quick sanity check on a specific commit or
+  diff
 Do NOT use when:
 * You are *processing* review feedback — use [`receiving-code-review`](../receiving-code-review/SKILL.md)
-* Branch is not yet code-complete — the review-request gate requires
-  green tests and a clean diff
-* Change is documentation-only with no behavior impact
+* The branch is not yet code-complete — the review-request gate
+  requires green tests and a clean diff
+* The change is documentation-only and has no behavior impact
 ## Goal
@@ -36,9 +38,9 @@ process. A well-framed review request **halves** review time and
 NEVER REQUEST REVIEW FROM A BRANCH YOU HAVE NOT REVIEWED YOURSELF.
 ```
-Self-review is the single cheapest filter. Catches the issues a human
-reviewer would flag in round one, so the human can spend time on
-issues only they can see.
+Self-review is the single cheapest filter. It catches the issues a
+human reviewer would flag in round one, so the human reviewer can
+spend time on the issues only they can see.
 ## Procedure
@@ -46,18 +48,19 @@ issues only they can see.
 Before asking anyone else:
-* Read the full diff (`git diff <base>...<head>`), not just files you
-  remember touching
+* Read the full diff (`git diff <base>...<head>`), not just the files
+  you remember touching
 * Check for accidental debug output, dead code, leftover `dd()`,
   `console.log`, commented-out blocks
 * Check for secrets in diff — API keys, connection strings, tokens
 * Check file-system side effects — generated files, lockfile churn,
   IDE configs, `.env` changes
 * Run the linter + tests (see [`verify-before-complete`](../verify-before-complete/SKILL.md))
-* Find issues → fix them, do **not** ship and hope the reviewer flags
+* If you find issues → fix them, do **not** ship them and hope the
+  reviewer flags them
-Use [`review-changes`](../../commands/review-changes.md) as the
-structured walk-through.
+Use the [`review-changes`](../../commands/review-changes.md) command
+as the structured walk-through.
 ### 2. Establish the diff baseline
@@ -78,8 +81,8 @@ review 80 unrelated commits.
 ### 3. Write the review request context
-Any review request must answer four questions. Missing any → the
-reviewer will ask, and that round trip is preventable.
+Any review request must answer four questions. If any is missing, the
+reviewer will ask — and that round trip is preventable.
 | Question | Where it lives |
 |---|---|
@@ -96,22 +99,24 @@ for the title format.
 ### 4. Keep the PR reviewable in size
 * Target < 400 lines of real diff (excluding generated / lockfiles)
-* Bigger — consider splitting into a stack (refactor PR → feature PR)
-  so reviewers can handle each in one sitting
-* Flag generated files explicitly in the description so reviewers skip
-* Never mix a refactor + behavior change in one PR — reviewers cannot
-  isolate the risk
+* If bigger — consider splitting into a stack (refactor PR → feature
+  PR) so reviewers can handle each in one sitting
+* Flag generated files explicitly in the description so reviewers
+  skip them
+* Never mix a refactor + behavior change in the same PR — reviewers
+  cannot isolate the risk
 ### 5. Pick the right reviewer set
-* **Architectural impact** → code owner for the affected area
-* **Security-sensitive** → a security-reviewer role if the project has one
+* **Architectural impact** → the code owner for the affected area
+* **Security-sensitive** → a security-reviewer role if the project has
+  one
 * **Bots** → let Copilot / Greptile / Augment run automatically; do not
   gate human review on bot completion
 * **Cross-team change** → each affected team's owner
-Project with a `CODEOWNERS` file → GitHub handles this automatically;
-do not override without a reason.
+If the project has a `CODEOWNERS` file, GitHub handles this
+automatically — do not override without a reason.
 ### 6. Send and wait — do not nudge early
@@ -119,8 +124,8 @@ After the PR is open:
 * Respond to questions, not to the implicit "where is my review?"
   schedule
-* Review blocking and overdue → a single short nudge is appropriate;
-  do not re-open or force-push to bump the PR list
+* If the review is blocking and overdue → a single short nudge is
+  appropriate; do not re-open or force-push to bump the PR list
 When review comments arrive → switch to
 [`receiving-code-review`](../receiving-code-review/SKILL.md).
@@ -144,9 +149,9 @@ When handing the review request to the reviewer (PR body, Slack, email):
 * A 1000-line PR with "no behavior change" still needs review — the
   reviewer has no way to confirm "no behavior change" without reading
   every line
-* Auto-merge on approval bypasses re-review after later force-pushes —
-  use deliberately, not by habit
-* A PR description saying "see the code" is not a description —
+* Auto-merge on approval bypasses re-review after later force-pushes
+  — use deliberately, not by habit
+* A PR description that says "see the code" is not a description —
   reviewers need the why
 * Requesting review from someone without context (new hire, other
   team) without a longer pairing — they cannot do a deep review cold

package/.agent-src/skills/security/SKILL.md CHANGED Viewed

@@ -11,8 +11,13 @@ source: package
 Use when implementing authentication, authorization, or any security-sensitive functionality.
 Do NOT use when:
-- Validation logic only (use `laravel-validation` skill)
-- Full security audit (use `security-audit` skill)
+* Validation logic only — route to [`laravel-validation`](../laravel-validation/SKILL.md)
+* Full security audit — route to [`security-audit`](../security-audit/SKILL.md)
+* You need a pre-implementation threat model — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* You need end-to-end authorization analysis — route to
+  [`authz-review`](../authz-review/SKILL.md)
 ## Procedure: Implement security for a feature

package/.agent-src/skills/security-audit/SKILL.md CHANGED Viewed

@@ -24,9 +24,13 @@ Use this skill when:
 Do NOT use when:
-- Writing new auth/policy code → use `security`
-- Hunting for functional bugs → use `bug-analyzer` (proactive mode)
-- Investigating performance → use `performance-analysis`
+* Writing new auth/policy code — route to [`security`](../security/SKILL.md)
+* Hunting for functional bugs — route to [`bug-analyzer`](../bug-analyzer/SKILL.md) (proactive mode)
+* Investigating performance — route to [`performance-analysis`](../performance-analysis/SKILL.md)
+* You need a pre-implementation threat model for a new feature — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* You need end-to-end authorization analysis for one route/action — route to
+  [`authz-review`](../authz-review/SKILL.md)
 ## Procedure: Security audit

package/.agent-src/skills/systematic-debugging/SKILL.md CHANGED Viewed

@@ -8,8 +8,8 @@ source: package
 ## When to use
-* Test fails and failure is not self-explanatory
-* Bug reported (Jira, Sentry, user message), root cause not obvious
+* A test fails and the failure is not self-explanatory
+* A bug is reported (Jira, Sentry, user message) and the root cause is not obvious
 * Production or staging shows unexpected behavior
 * Code behaves differently than the developer expected
 * A previous fix did not resolve the issue or introduced a new one
@@ -17,14 +17,19 @@ source: package
 Do NOT use when:
-* Failure message names the fix (typo, missing import, obvious off-by-one) — fix it
+* The failure message already names the fix (typo, missing import, obvious
+  off-by-one) — fix it and move on
 * Pure style / formatting / lint issues
 * Documentation-only questions
+* You need a static trace of a specific data element — route to
+  [`data-flow-mapper`](../data-flow-mapper/SKILL.md)
+* You need to enumerate what a planned change will touch — route to
+  [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md)
 ## Goal
-Find the **root cause** before changing any code. A symptom fix papering
-over an unknown cause is a regression waiting to happen.
+Find the **root cause** before changing any code. A symptom fix that
+papers over an unknown cause is a regression waiting to happen.
 ## The Iron Law
@@ -37,30 +42,31 @@ diff, a reproduced failure — those are evidence.
 ## Procedure
-Complete each phase before the next. Skipping ahead is the single
-biggest cause of wasted debug time.
+Complete each phase before starting the next. Skipping ahead is the
+single biggest cause of wasted debug time.
 ### Phase 1 — Reproduce
-Goal: make the failure happen on demand, smallest possible setup.
+Goal: make the failure happen on demand, with the smallest possible setup.
-1. Read the error message, stack trace, and logs **in full**. Note exact
-   file, line, and the chain of calls above it.
-2. Identify the minimum input, state, or action sequence triggering the
-   failure. Intermittent → gather more data before guessing.
+1. Read the error message, stack trace, and logs **in full**. Note the
+   exact file, line, and the chain of calls above it.
+2. Identify the minimum input, state, or sequence of actions that
+   triggers the failure. If it is intermittent — gather more data before
+   guessing.
 3. Capture the exact reproduction as a command or a test. Prefer a
    failing test (see [`test-driven-development`](../test-driven-development/SKILL.md))
-   — turns Phase 4 into a verified fix.
+   — it turns Phase 4 into a verified fix.
-Cannot reproduce? You do not yet understand the bug. Stop. Add logging,
-re-run, collect more evidence.
+If you cannot reproduce, you do not yet understand the bug. Stop. Add
+logging, re-run, collect more evidence.
 ### Phase 2 — Isolate
 Goal: locate the failure in a single component, layer, or call site.
-1. Bisect the surface area. Smallest code path that still fails? Turn
-   off/skip/mock adjacent features to narrow the window.
+1. Bisect the surface area. What is the smallest code path that still
+   fails? Turn off/skip/mock adjacent features to narrow the window.
 2. For multi-component systems (frontend → API → service → DB, or
    CI → build → deploy), log at **each boundary**:
@@ -68,7 +74,8 @@ Goal: locate the failure in a single component, layer, or call site.
    * What leaves the component
    * What config/env the component actually sees
-   Goal: answer "which boundary has expected ≠ actual?".
+   The goal is not to fix — it is to answer "which boundary is the one
+   where expected ≠ actual?".
 3. Check recent changes: `git log`, `git blame` on the failing line,
    recent dependency updates, config edits, infra changes.
 4. **Consult memory for prior matches.** Via
@@ -81,13 +88,13 @@ Goal: locate the failure in a single component, layer, or call site.
        limit=3,
    )
    ```
-   A matching `incident-learning` may already name the root cause, fix,
-   and regression test. A matching `historical-pattern` narrows the
-   hypothesis space before Phase 3. Cite matching `id`s in the evidence
-   trail.
-5. Trace backwards from the symptom. `null` arrives at line 42 — where
-   does the value originate? Walk up the call stack until the origin is
-   found. Fix at origin, not at line 42.
+   A matching `incident-learning` may already name the root cause, the
+   fix, and the regression test. A matching `historical-pattern`
+   narrows the hypothesis space before Phase 3. Cite matching `id`s in
+   the Phase 1–4 evidence trail.
+5. Trace backwards from the symptom. If `null` arrives at line 42 —
+   where does the value originate? Walk up the call stack until the
+   origin is found. Fix at origin, not at line 42.
 ### Phase 3 — Hypothesize
@@ -95,35 +102,35 @@ Goal: one testable hypothesis at a time, rejected or confirmed by evidence.
 1. State the hypothesis in one sentence: *"The failure happens because
    X, which I can confirm by observing Y."*
-2. Design the smallest possible experiment that confirms or rejects the
-   hypothesis. One variable at a time.
+2. Design the smallest possible experiment that either confirms or
+   rejects the hypothesis. One variable at a time.
 3. Run it. Read the output.
-4. Confirmed → Phase 4. Rejected → back to Phase 2 with new
+4. If confirmed → Phase 4. If rejected → back to Phase 2 with the new
    information, then form a new hypothesis.
-Three hypotheses in a row fail → stop. You do not understand the system
-well enough yet, or the architecture itself is the problem — see
+If three hypotheses in a row fail, stop. You do not understand the
+system well enough yet, or the architecture is the problem itself — see
 "Three-strike rule" below.
 ### Phase 4 — Verify the fix
 Goal: the fix resolves the root cause, not just the observed symptom.
-1. Write or update a failing test reproducing the bug (if not already
-   done in Phase 1).
+1. Write or update a failing test that reproduces the bug (if not
+   already done in Phase 1).
 2. Apply a single, minimal fix targeting the root cause. No bundled
    refactors, no "while I'm here".
-3. Re-run the reproduction — failure gone.
-4. Re-run the surrounding test suite — nothing adjacent turned red.
-5. Read output carefully — no new warnings, deprecations, or silent
-   retries masking the same bug recurring.
+3. Re-run the reproduction — the failure is gone.
+4. Re-run the surrounding test suite — nothing adjacent has turned red.
+5. Read the output carefully — no new warnings, deprecations, or
+   silent retries that would mask the same bug recurring.
-Fix does not work? **Do not** stack a second fix on top. Go back to
-Phase 2, treat the failure as new evidence.
+If the fix does not work, **do not** stack a second fix on top. Go back
+to Phase 2, treat the failure as new evidence.
 ## Three-strike rule
-After **three** attempted fixes with the bug still present:
+If you have tried **three** fixes and the bug is still present:
 * Stop attempting fixes.
 * Re-read phases 1–3 — something about the root cause is wrong.
@@ -150,7 +157,7 @@ right line beats five minutes of IDE breakpoints.
 ## Condition-based waiting (intermittent bugs)
 Intermittent tests and race conditions usually stem from waiting on
-time instead of a condition. Replace `sleep(100)` or
+time instead of on a condition. Replace `sleep(100)` or
 `setTimeout(r, 100)` with an explicit wait-for:
 ```ts
@@ -172,11 +179,12 @@ async function waitFor<T>(
 ```
 Only use an arbitrary timeout when the timing itself is the contract
-(debounce, throttle) — add a comment explaining **why** the exact value.
+(debounce, throttle) — and add a comment explaining **why** the exact
+value.
 ## Output format
-When reporting debug findings:
+When reporting debug findings to the user:
 1. **Symptom** — what was observed (one sentence + failure message)
 2. **Reproduction** — the command or test that triggers it
@@ -189,27 +197,27 @@ When reporting debug findings:
 * Reading half a stack trace and jumping to a fix — the actual cause is
   usually two or three frames above the one you read.
-* "It works on my machine" — different env than the bug report.
-  Reproduce with exact conditions from the report.
-* Adding a retry or sleep to mask an intermittent failure — hides the
-  race condition, does not fix it. Use condition-based waiting.
-* Fixing the first line that throws when the bad value came from up the
-  call chain. Trace backwards to the origin.
+* "It works on my machine" — you are running a different env than the
+  bug report. Reproduce with the exact conditions from the report.
+* Adding a retry or sleep to mask an intermittent failure — this hides
+  the race condition, it does not fix it. Use condition-based waiting.
+* Fixing the first line that throws, when the bad value came from
+  somewhere up the call chain. Trace backwards to the origin.
 * "The fix works, the test is just flaky" — flaky tests are bugs in the
   test or the code. Diagnose them, do not retry-until-green.
-* Turning a failing assertion into a softer one ("maybe 2 or 3 retries,
-  accept both") to make it pass.
-* Bundling a bug fix with a refactor — test goes red again, cannot tell
-  which change broke it.
+* Turning a failing assertion into a softer one ("maybe it's 2 or 3
+  retries, let's accept both") to make it pass.
+* Bundling a bug fix with a refactor — if the test goes red again you
+  cannot tell which change broke it.
 ## Red flags — STOP and restart from Phase 1
 * "Let me just try X and see if it works"
 * "I don't fully understand it, but this probably fixes it"
 * Proposing a fix without having reproduced the bug
-* Bundling multiple changes in one attempt
+* Bundling multiple changes in one attempt ("fixing this and refactoring that")
 * "It's probably a race condition, let me add a sleep"
-* A green test run after changes without having first seen it red
+* A green test run after changes, without having first seen it red
 * "This looks similar to bug X, so it's the same fix"
 * Suppressing a log, warning, or exception instead of tracing its source
@@ -219,7 +227,7 @@ When reporting debug findings:
 * Do NOT change two things at once in a single experiment
 * Do NOT silence a warning, failing test, or noisy log as a "fix"
 * Do NOT mark a bug as fixed without a regression test
-* Do NOT attempt fix #4 after three failed fixes — surface the pattern
+* Do NOT attempt fix #4 after three failed fixes — surface the pattern instead
 ## When to hand over to another skill
@@ -234,11 +242,11 @@ When reporting debug findings:
 Before declaring a bug fixed:
-* [ ] Failure was reproduced before any code changed
-* [ ] Root cause named explicitly, not "probably"
+* [ ] The failure was reproduced before any code changed
+* [ ] The root cause is named explicitly, not "probably"
 * [ ] Evidence (log, trace, diff) supports the named root cause
-* [ ] Failing test reproducing the bug was added or updated
-* [ ] Fix is minimal, targets the root cause, not the symptom
-* [ ] Regression test now passes
+* [ ] A failing test reproducing the bug was added or updated
+* [ ] The fix is minimal and targets the root cause, not the symptom
+* [ ] The regression test now passes
 * [ ] Adjacent tests still pass
 * [ ] No warning or suppressed output hides a recurrence

package/.agent-src/skills/test-driven-development/SKILL.md CHANGED Viewed

@@ -9,23 +9,23 @@ source: package
 ## When to use
 * Adding a new function, method, or behavior
-* Fixing a bug (bug needs a regression test before the fix)
+* Fixing a bug (the bug needs a regression test before the fix)
 * Refactoring a unit whose current behavior is unclear
 * Any task where expected behavior can be expressed as an assertion
 Do NOT use when:
-* Throwaway prototype or spike code explicitly marked as exploration
-* Boilerplate generation (migrations, config, scaffolding)
-* Pure documentation (`.md`, `AGENTS.md`, README)
+* Writing throwaway prototype or spike code explicitly marked as exploration
+* Generating boilerplate (migrations, config files, scaffolding)
+* Editing pure documentation (`.md`, `AGENTS.md`, README)
 * Working inside this `agent-config` package on skill/rule markdown
 ## Goal
-* Drive implementation from a verified-failing test, not the agent's
-  belief that code "should work".
-* Catch edge cases **before** production bugs.
-* Leave every change with a regression test running in CI.
+* Drive implementation from a verified-failing test, not from the agent's
+  belief that the code "should work".
+* Catch edge cases **before** they become production bugs.
+* Leave every change with a regression test that runs in CI.
 ## The core discipline
@@ -38,7 +38,7 @@ Do NOT use when:
 ```
 If step 2 is skipped, the test is not trusted — a test that has never
-failed proves nothing.
+failed proves nothing about the code under test.
 ## Procedure
@@ -46,21 +46,21 @@ failed proves nothing.
 State in one sentence: *"When X happens, the system should do Y."*
-Cannot state in one sentence? Scope too big — split into multiple tests,
-one sentence each.
+If you cannot state it in one sentence, the scope is too big — split into
+multiple tests, each covering one sentence.
 ### 2. Write the failing test first
-Smallest test expressing step-1 sentence.
+Write the smallest test that expresses the sentence from step 1.
-* One assertion per behavior (multiple assertions OK only when describing
-  the same single behavior).
+* One assertion per behavior (multiple assertions are OK only when they
+  describe the same single behavior).
 * Real code paths, not mocks — mock only at I/O boundaries (HTTP, DB, time).
-* Descriptive name: `it_rejects_empty_email`, not `test_email_1`.
+* Use a descriptive name: `it_rejects_empty_email`, not `test_email_1`.
 ### 3. Run the test and watch it fail
-Execute the single test (targeted, not full suite):
+Execute the single test (targeted, not the full suite):
 ```bash
 # PHP/Pest
@@ -72,26 +72,27 @@ npx vitest run --testNamePattern "rejects empty email"
 Required observations **before proceeding**:
-* Test **fails** (not errors).
-* Failure message matches expectation (missing behavior, not typo).
-* Passes immediately → it does not test what you think. Fix the test,
-  do not start writing production code.
+* The test **fails** (not errors).
+* The failure message matches what you expected (missing behavior, not typo).
+* If the test passes immediately → it does not test what you think. Fix
+  the test, do not start writing production code.
 ### 4. Write minimum code to pass
-**Just enough** production code to make the test green. No extra
+Add **just enough** production code to make the test green. No extra
 features, no unrelated refactoring, no "while I'm here" cleanups.
-Urge to add a parameter, edge case, or helper not covered by current
-test → stop. Belongs in the next RED step, not this GREEN step.
+If you feel the urge to add a parameter, edge case, or helper not covered
+by the current test — stop. That belongs in the next RED step, not this
+GREEN step.
 ### 5. Run again and watch it pass
 Re-run the same targeted command. Required:
-* New test passes.
-* No previously green tests turned red.
-* Output clean (no new warnings, deprecations, or noise).
+* The new test passes.
+* No previously green tests have turned red.
+* Test output is clean (no new warnings, deprecations, or noise).
 ### 6. Refactor (only if green)
@@ -101,8 +102,8 @@ With all tests green, you may:
 * Extract duplication into helpers
 * Tighten types
-Do **not** add new behavior during refactor — needs its own failing test
-first. Re-run tests after refactor to confirm still-green.
+Do **not** add new behavior during refactor — that needs its own failing
+test first. Re-run tests after the refactor to confirm still-green.
 ### 7. Repeat for the next behavior
@@ -110,25 +111,25 @@ Back to step 1 with the next single-sentence behavior.
 ## Output format
-1. Failing test (file + test name) with captured failure output
-2. Minimum-code diff that makes it pass
+1. The failing test (file + test name) with captured failure output
+2. The minimum-code diff that makes it pass
 3. Captured green-run output
-4. Refactor diff (optional)
+4. Any refactor diff (optional)
 ## Anti-rationalizations table
-The urge to skip TDD is strongest when TDD matters most. Name the
-rationalization and reject it:
+The urge to skip TDD is strongest on tasks where TDD matters most. Name
+the rationalization and reject it:
 | Thought | Reality |
 |---|---|
-| "Too simple to need a test" | Simple code still breaks. A test costs less than one debug cycle. |
-| "I'll add the test after the code works" | A test written after code passes on first run — never failed. Proves nothing. |
-| "I already ran it manually" | Manual runs not repeatable. Next edit breaks it silently. |
-| "Deleting code I just wrote is wasteful" | Sunk cost. Cheap path: delete, write test, reimplement minimally. |
-| "I'll keep the code as reference while I write the test" | You will adapt it. That is test-after-the-fact with extra steps. Delete it. |
-| "I just need to explore the API first" | Spike on a throwaway branch. Then delete and restart with TDD. |
-| "The test is too hard to write" | Signals a design problem in the code, not the test. Listen. |
+| "This is too simple to need a test" | Simple code still breaks. A test takes less time than one debug cycle. |
+| "I'll add the test after the code works" | A test written after code passes on the first run — it has never failed. It does not prove the code is correct. |
+| "I already ran it manually" | Manual runs are not repeatable. The next edit breaks it silently. |
+| "Deleting this code I just wrote is wasteful" | Sunk cost. The cheap path is: delete, write the test, reimplement minimally. |
+| "I'll keep the code as reference while I write the test" | You will read it and adapt it. That is test-after-the-fact with extra steps. Delete it. |
+| "I just need to explore the API first" | Spike it on a throwaway branch. Then delete it and restart with TDD. |
+| "The test is too hard to write" | That signals a design problem in the code, not in the test. Listen to it. |
 | "This bug is urgent, no time for a test" | The test **is** the fastest path to a verified fix. Guessing takes longer. |
@@ -162,7 +163,7 @@ final class EmailValidator
 }
 ```
-Run filter again → passes. No additional rules (format, MX, length)
+Run the filter again → passes. No additional rules (format, MX, length)
 until a next failing test drives them.
 ### JS / Vitest
@@ -184,7 +185,7 @@ it('retries a failing operation up to 3 times', async () => {
 ```
 Run: `npx vitest run --testNamePattern "retries a failing"` → fails
-(`retry` undefined).
+(`retry` is undefined).
 ```ts
 // src/retry.ts — GREEN (minimum)
@@ -197,21 +198,22 @@ export async function retry<T>(op: () => Promise<T>): Promise<T> {
 }
 ```
-Run again → passes. Configurable attempt count, backoff, jitter all
+Run again → passes. Configurable attempt count, backoff, and jitter all
 wait for their own failing tests.
 ## Gotchas
 * Running the full suite instead of a filtered test hides the RED→GREEN
   signal in noise. Always target first.
-* A test that passes on the very first run is not TDD — written against
-  existing code.
+* A test that passes on the very first run is not TDD — it was written
+  against code that already exists.
 * `expect()` with three or four assertions on unrelated fields describes
   multiple behaviors. Split them.
-* Snapshot tests invert the discipline — they generate the expected
-  value from the code. Only use where human-readable output is the
-  contract (CLI, SQL strings).
-* Mocking the thing under test (instead of its I/O) tests the mock.
+* Snapshot tests invert the discipline — they generate the expected value
+  from the code. Only use snapshots where human-readable output is the
+  contract (CLI output, SQL strings).
+* Mocking the thing under test (instead of its I/O) tests the mock, not
+  the code.
 ## Do NOT
@@ -219,22 +221,22 @@ wait for their own failing tests.
   and has been observed to fail
 * Do NOT accept a test that never failed as evidence the code works
 * Do NOT bundle refactors into the GREEN step
-* Do NOT silence a flaky test — diagnose or delete it
-* Do NOT skip the targeted RED-run because "I know it fails"
+* Do NOT silence a flaky test — diagnose it, or delete it
+* Do NOT skip the targeted RED-run because "I just wrote it, I know it fails"
 ## Anti-patterns
 * `it('works')` — no behavior described
 * One test covering "and/and/and" — split per behavior
-* Test reaching into private state instead of observable behavior
-* Test duplicating the production code's algorithm (tautology)
+* Test that reaches into private state instead of testing observable behavior
+* Test that duplicates the production code's algorithm (tautology)
 ## When to hand over to another skill
 * Quality tools, PHPStan, ECS, Rector → [`quality-tools`](../quality-tools/SKILL.md)
 * Full Pest conventions, Laravel testing helpers → [`pest-testing`](../pest-testing/SKILL.md)
 * Running tests inside Docker → [`tests-execute`](../tests-execute/SKILL.md)
-* Investigating why a test fails for non-obvious reasons →
+* Investigating why a test is failing for non-obvious reasons →
   [`systematic-debugging`](../systematic-debugging/SKILL.md)
 ## Validation checklist
@@ -243,10 +245,10 @@ Before marking TDD work complete:
 * [ ] Every new behavior has a test
 * [ ] Each test was observed to fail first, with a matching failure message
-* [ ] Minimum code was written to turn each RED into GREEN
+* [ ] The minimum code was written to turn each RED into GREEN
 * [ ] All targeted tests pass
-* [ ] No adjacent test turned red
-* [ ] Output clean (no new warnings or deprecations)
+* [ ] No adjacent test has turned red
+* [ ] Test output is clean (no new warnings or deprecations)
 See also [`developer-like-execution`](../developer-like-execution/SKILL.md)
 for the broader think → analyze → verify loop this skill plugs into.