@event4u/agent-config 1.16.0 → 1.17.0

package/.agent-src/skills/receiving-code-review/SKILL.md

@@ -10,9 +10,10 @@ source: package
 
 ## When to use
 
-* PR has review comments (bots like Copilot, Greptile, Augment, or human
-  reviewers) and the next step is addressing them
-* Someone pasted review feedback and asks you to "fix it" or "handle it"
+* A PR has review comments (from bots like Copilot, Greptile, Augment,
+  or from human reviewers) and the next step is to address them
+* Someone pasted review feedback into the conversation and asks you
+  to "fix it" or "handle it"
 * A pair-programming partner gave verbal suggestions about code you
   just wrote
 * You are tempted to reply "you are absolutely right" before reading
@@ -21,10 +22,10 @@ source: package
 Do NOT use when:
 
 * You are writing a review yourself (different discipline)
-* User explicitly asks for blind implementation of a specific change
-  not framed as review feedback
-* Pure style/formatting the linter should decide automatically — run
-  the linter
+* The user explicitly asks for blind implementation of a specific change
+  that is not framed as review feedback
+* The feedback is pure style/formatting that a linter should decide
+  automatically — just run the linter
 
 ## Goal
 
@@ -40,40 +41,42 @@ NO IMPLEMENTATION UNTIL THE FEEDBACK IS UNDERSTOOD AND VERIFIED.
 ```
 
 A "fix" implemented against a misread comment is worse than no fix —
-ships the wrong behavior under the label of "addressed feedback".
+it ships the wrong behavior under the label of "addressed feedback".
 
 ## Procedure
 
 ### 1. Read the full comment set before touching code
 
 Read **every** open comment on the PR first. Comments often relate to
-each other — fixing comment #3 in isolation can conflict with #5. Group:
+each other — fixing comment #3 in isolation can conflict with comment
+#5. Group them:
 
 * **Blocking** — breaks behavior, introduces a bug, security issue
-* **Important** — logic correct but design / readability issue
+* **Important** — logic is correct but design / readability issue
 * **Minor** — naming, comment style, formatting the linter missed
-* **Wrong** — reviewer misunderstood the code, or suggestion regresses
-  another behavior
+* **Wrong** — reviewer misunderstood the code, or suggestion would
+  regress another behavior
 
 ### 2. Restate each comment in your own words
 
 For every comment, write (internally or to the user): *"The reviewer
 is asking me to X because Y."*
 
-Cannot complete that sentence confidently → the comment is unclear. Ask
-for clarification **before** implementing anything. Do not implement
-the clear ones first and ask later — they may be linked.
+If you cannot complete that sentence confidently → the comment is
+unclear. Ask for clarification **before** implementing anything. Do
+not implement the clear ones first and ask later — they may be linked.
 
 ### 3. Verify each claim against the code
 
-For each blocking/important comment:
+For each comment classified as blocking/important:
 
 * Reproduce the alleged issue locally (run the test, hit the endpoint,
   read the actual runtime value — see [`systematic-debugging`](../systematic-debugging/SKILL.md))
 * Check what the code actually does, not what the reviewer **thinks**
   it does
 * Check whether the suggested fix would break another test or caller
-* Check `git blame` / history — current code may be that way for a reason
+* Check `git blame` / history — the current code may be the way it is
+  for a reason
 * **Consult memory for prior context.** Via
   [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md),
   call `retrieve(types=["historical-patterns", "architecture-decisions"],
@@ -86,21 +89,21 @@ For each blocking/important comment:
 
 | Situation | Response |
 |---|---|
-| Reviewer right, fix local, no caller impact | Implement, reference the comment in the commit message |
-| Reviewer right but fix affects other callers | Note downstream effects in the reply, then implement |
-| Reviewer wrong — misreading the code | Reply with evidence (specific line / test / value), do not change code |
+| Reviewer is right, fix is local, no caller impact | Implement, reference the comment in the commit message |
+| Reviewer is right but fix affects other callers | Note the downstream effects in the reply, then implement |
+| Reviewer is wrong — based on misreading the code | Reply with evidence (specific line / test / value), do not change code |
 | Reviewer suggests a feature the codebase does not use (YAGNI) | Reply asking whether the feature is actually needed, do not build speculatively |
 | Reviewer and user / architecture disagree | Escalate to the user before implementing either path |
 
 ### 5. Reply in the right place, with the right tone
 
-* Inline PR comments → reply **in the thread** of that comment, not as
-  a top-level PR comment
+* For inline PR comments → reply **in the thread** of that comment,
+  not as a top-level PR comment
 * Quote **evidence**, not opinion — "line 47 already handles this via
   `$x->isNull()`" beats "I think that's fine"
 * No flattery. No "great catch", "absolutely right", "thanks for
-  noticing". The `language-and-tone` rule already bans this — actions
-  are the acknowledgement
+  noticing". The existing `language-and-tone` rule already bans this —
+  actions are the acknowledgement
 * If you were wrong in your earlier pushback, state it factually and
   move on. No long apology
 
@@ -108,11 +111,11 @@ For each blocking/important comment:
 
 1. Blocking issues first
 2. Important issues next
-3. Minor issues last (or bundle into a single commit)
+3. Minor issues last (or bundle them into a single commit)
 4. Wrong / YAGNI: no code change, only a reply with reasoning
 
-Run relevant tests and linters **between** each group — do not batch
-four changes and then run tests once. See
+Run the relevant tests and linters **between** each group — do not
+batch four changes and then run tests once. See
 [`verify-before-complete`](../verify-before-complete/SKILL.md).
 
 ## Output format
@@ -122,34 +125,36 @@ When reporting back to the user after handling review:
 1. **Triage table** — comment → classification → decision
 2. **Implemented changes** — bullet per change with file + commit ref
 3. **Pushed back** — bullet per rejected comment with the evidence
-4. **Outstanding** — anything awaiting clarification, with the specific
-   question
+4. **Outstanding** — anything awaiting clarification, with the
+   specific question
 
 ## Gotchas
 
 * Bot comments (Copilot, Greptile) are **not** automatically right.
-  Frequently flag false positives on patterns the codebase uses
-  deliberately. Verify like a human comment.
-* A comment reading like a question ("should this be X?") is often a
-  polite way of saying "change it to X". Ask if unclear.
+  They frequently flag false positives on patterns the codebase uses
+  deliberately. Verify like you would a human comment.
+* A comment that reads like a question ("should this be X?") is often
+  a polite way of saying "change it to X". Ask if unclear instead of
+  guessing the register.
 * Resolving a comment in the GitHub UI without an accompanying fix or
-  reply silently marks it handled — reviewers may miss the lack of
-  substance.
+  reply silently marks it handled — reviewers may not notice the lack
+  of substance.
 * Stacked PRs — a comment on the base PR may already be fixed in the
   child PR. Check both before touching code.
 * A suggestion that passes review aesthetics but fails the test suite
   is still a regression. Run tests even when "the change is trivial".
-* Flattery leaks in as "good point" or "thanks". Delete before sending.
+* Flattery leaks in as "good point" or "thanks". Delete before
+  sending. The code change itself is the acknowledgement.
 
 ## Do NOT
 
 * Do NOT reply "you are absolutely right", "great catch", or any
   flattery variant — actions acknowledge, words do not
 * Do NOT implement a suggestion before verifying it against the code
-* Do NOT fix the clear items first and ask about the unclear ones later
-  when the items are linked
-* Do NOT accept a reviewer's suggestion that conflicts with an explicit
-  architectural decision without raising it
+* Do NOT fix the clear items first and ask about the unclear ones
+  later when the items are linked
+* Do NOT accept a reviewer's suggestion that conflicts with an
+  explicit architectural decision without raising it
 * Do NOT batch multiple unrelated fixes into one commit — reviewers
   cannot re-review selectively
 * Do NOT mark a comment resolved without either a code change or a
@@ -159,15 +164,15 @@ When reporting back to the user after handling review:
 
 * Replying "Fixed!" after a commit that does not actually address the
   comment (wrong file, missed case)
-* Rewriting the comment author's suggestion into your own words without
-  checking whether the reinterpretation still matches intent
+* Rewriting the comment author's suggestion into your own words
+  without checking whether the reinterpretation still matches intent
 * Implementing the YAGNI-suggested feature "just in case" the reviewer
   comes back
 * Silent disagreement — ignoring a comment without a reply
 
 ## When to hand over to another skill / command
 
-* Executing fixes across many comments → [`fix-pr-comments`](../../commands/fix-pr-comments.md)
+* Executing the fixes across many comments → [`fix-pr-comments`](../../commands/fix-pr-comments.md)
   (handles both bot + developer), [`fix-pr-bot-comments`](../../commands/fix-pr-bot-comments.md),
   [`fix-pr-developer-comments`](../../commands/fix-pr-developer-comments.md)
 * Running the full verification gate before pushing replies →
@@ -181,10 +186,10 @@ When reporting back to the user after handling review:
 
 Before considering review handling done:
 
-* [ ] Every open comment read, classified, decision made
-* [ ] No comment implemented without a one-sentence restatement
-* [ ] Every implemented fix verified by a test or runtime check
+* [ ] Every open comment has been read, classified, and has a decision
+* [ ] No comment was implemented without a one-sentence restatement
+* [ ] Every implemented fix has been verified by a test or runtime check
 * [ ] Every rejected comment has a reply quoting evidence
-* [ ] No comment marked resolved without code change or reply
+* [ ] No comment was marked resolved without code change or reply
 * [ ] No reply contains flattery
 * [ ] Linters and relevant tests pass after the changes

package/.agent-src/skills/refine-prompt/SKILL.md

@@ -217,4 +217,3 @@ For `low`, the question replaces the AC list:
 - [`work_engine.scoring.confidence`](../../templates/scripts/work_engine/scoring/confidence.py) — rubric + band thresholds
 - [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one-question-per-turn Iron Law
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it
-- `agents/roadmaps/archive/road-to-prompt-driven-execution.md` — Phase 3 owns this skill (archived on completion)

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

@@ -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

@@ -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

@@ -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

@@ -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