@event4u/agent-config 1.9.1

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

@@ -0,0 +1,310 @@
+---
+name: "refine-ticket"
+description: "Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt."
+personas:
+  - developer
+  - senior-engineer
+  - product-owner
+  - stakeholder
+  - critical-challenger
+  - ai-agent
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# Refine Ticket
+
+> Move a ticket from "raw idea" to "implementation-ready" in one run.
+> Produces a rewritten ticket, Top-5 risks, and persona voices.
+> Orchestrates `validate-feature-fit` and `threat-modeling` as sub-skills
+> — never duplicates their logic. Output is copy-paste ready; the user
+> decides write-back.
+
+## When to use
+
+- The user hands over a Jira / Linear ticket key, URL, branch name, or
+  pasted ticket text and asks for a sanity check before planning.
+- A ticket looks too vague, too broad, or smells wrong.
+- Before `/feature-plan` or `/feature-explore` on a ticket-anchored scope.
+- The user says "tighten the AC", "poke holes in this ticket",
+  "is this ready to plan?", "ist das Ticket klar genug?",
+  "verbessere das Ticket".
+
+## When NOT to use (near-misses)
+
+| Phrasing | Route to |
+|---|---|
+| "plan this feature" | `/feature-plan` (downstream) |
+| "estimate this ticket" | `/estimate-ticket` (sibling, Phase 4) |
+| "is this a duplicate feature?" | `validate-feature-fit` (sub-skill) |
+| "threat-model this change" | `threat-modeling` (sub-skill) |
+| "investigate this bug" | `/bug-investigate` (bug-focused) |
+
+`/refine-ticket` **orchestrates** these — it does not replace them.
+
+## Language strategy
+
+Pick output prose language once, up front; apply to every section.
+First hit wins:
+
+1. **User-message language.** Latest user message decides. Honours the
+   global `language-and-tone` iron law.
+2. **Ticket body language.** When the user's message is ambiguous
+   (one-word `/refine-ticket PROJ-123`), mirror the language the ticket
+   is written in (summary + description).
+3. **`.agent-settings.yml` default** (`personal.language` or equivalent).
+   If missing, default to English.
+
+Quoted identifiers (keys, paths, commands, code) stay native. Only
+prose mirrors the picked language.
+
+## Inputs (four equivalent paths)
+
+Reuses the `jira-ticket` command's loader. Accepts:
+
+1. **Ticket key** — `/refine-ticket PROJ-123`
+2. **Branch detection** — `/refine-ticket` with no arg; regex
+   `[A-Z]+-[0-9]+` against `git branch --show-current`
+3. **Pasted text** — `/refine-ticket` followed by a markdown block
+4. **URL** — `/refine-ticket https://acme.atlassian.net/browse/PROJ-123`
+
+If none resolve to a ticket, fall back to conversational discovery
+(`feature-explore`-style): ask one focused question, then continue.
+
+## Procedure
+
+### 1. Load ticket
+
+Delegate to `jira-ticket` §1-3:
+- Extract ticket ID (branch / URL / arg).
+- Fetch via Jira API (`GET /issue/{id}`) — summary, description,
+  issue type, priority, status, comments, linked issues.
+- Scan description + comments for Sentry URLs; pull stacktrace /
+  tags when present.
+
+If pasted text: skip API, parse markdown, extract title + AC
+bullets + body.
+
+**Auto-fetch parent (Phase F4).** Before detection, check the issue
+type and fold parent context in:
+
+```python
+from scripts.refine_ticket_detect import (
+    issuetype_needs_parent, fold_parent_context,
+)
+
+if issuetype_needs_parent(ticket["issuetype"]):
+    parent_key = ticket["parent_key"]          # from `fields.parent.key`
+    parent = fetch_jira_issue(parent_key)      # +1 API call
+    ticket_body = fold_parent_context(
+        ticket_body, parent_body=parent["body"], parent_key=parent_key,
+    )
+```
+
+Rules:
+- Applies to `Story` and `Sub-task` (and Linear / Shortcut equivalents).
+  `Task` / `Bug` / `Epic` skip the auto-fetch unless a `parent` link is
+  populated — then the agent folds explicitly without the issuetype guard.
+- `fold_parent_context()` is idempotent; folding twice with the same
+  parent does not duplicate the block.
+- Parent fetch fails (404, permission, network) → skip the fold, append
+  to orchestration notes:
+  *"Parent `<key>` not reachable — AC may lack upstream context."*
+
+Parent AC lines surfaced this way must be cited verbatim in the refined
+output's *Open questions* section so the user sees which constraints
+come from the parent.
+
+### 2. Inspect ticket + detect orchestration triggers
+
+Check the loaded ticket for clarity signals before orchestrating:
+- Does the summary match the description body?
+- Are AC bullets concrete (observable / testable) or vague ("works well")?
+- Is the scope one feature, or multiple tangled together?
+- Any sentence that references an existing module name, feature flag, or domain concept?
+
+Then run the deterministic detection helper — do **not** re-derive trigger
+logic in prose:
+
+```bash
+python3 scripts/refine_ticket_detect.py <ticket-body-file>
+# or, inside the skill run:
+from scripts.refine_ticket_detect import detect, load_map
+decision = detect(ticket_body, load_map(), cwd=Path.cwd())
+```
+
+The helper consumes [`detection-map.yml`](detection-map.yml) (co-located
+in this skill folder) and returns:
+
+- `validate-feature-fit` — fires when ≥ 2 distinct feature-area keywords
+  appear in the body (see `sub_skills.validate-feature-fit.keywords`).
+- `threat-modeling` — fires on any auth / webhook / upload / queue /
+  secret / tenant / admin / PII / payment keyword, or a `CVE-YYYY-N`
+  regex match.
+- `repo_aware` — on when `.git/`, `agents/contexts/`, `composer.json`,
+  or `package.json` is present in the cwd; off otherwise.
+- When `repo_aware=True`, `decision.repo_context` is populated by
+  `gather_repo_context()`:
+  - `recent_branches` — up to 20 most recent local branches (naming
+    convention signal).
+  - `recent_commits` — up to 30 most recent commit subjects (active
+    modules + verb conventions).
+  - `context_docs` — every `agents/contexts/*.md` filename (domain
+    vocabulary).
+- Outside a repo the context is empty — the skill produces the same
+  output shape, minus repo-specific citations (graceful degrade).
+
+Use `repo_context.recent_branches` to anchor the "Refined ticket" title
+naming (e.g. `feat/` vs `fix/` vs `refactor/` prefix), and
+`repo_context.context_docs` to cite domain vocabulary in the Top-5
+risks instead of inventing terms.
+
+The match lists and `require_count` thresholds are owned by
+`detection-map.yml` — edit the map, not this skill. Tests:
+[`tests/test_refine_ticket_detect.py`](../../../tests/test_refine_ticket_detect.py)
+(17 cases, DE + EN fixtures, repo-aware + graceful-degrade coverage).
+
+### 3. Orchestrate
+
+For every `SubSkillDecision` with `fired=True`, invoke the named sub-skill
+with the ticket body as input:
+
+- `validate-feature-fit` → returns duplicate / scope-creep findings
+- `threat-modeling` → returns trust boundaries + abuse cases
+
+**Cite, don't copy** — the output references findings by sub-skill name and
+file:line where applicable. If a sub-skill reports zero findings, emit
+`fired → clean` in the orchestration section. Skipped sub-skills appear
+as `skipped (no trigger match)` — never silently omitted.
+
+Each fired finding must map to at least one entry in the Top-5 risks
+section; orchestration that does not influence the risks is waste.
+
+### 4. Apply personas
+
+Load the persona set from frontmatter (Core-6 default). Each persona
+reviews the ticket through its lens and produces one paragraph:
+
+- **Developer** — implementability, unknowns, test seams
+- **Senior Engineer** — architectural fit, blast radius, hidden deps
+- **Product Owner** — value, user story integrity, AC completeness
+- **Stakeholder** — deadline fit, business impact, comms plan
+- **Critical Challenger** — devil's advocate; what's wrong with this?
+- **AI Agent** — automation hooks, tool boundaries, clarity for agents
+
+Optional: `--personas=+qa` adds the QA persona (edge cases, regression
+risk, test matrix).
+
+### 5. Synthesize + close-prompt
+
+Produce the three-section output (template below). After rendering,
+emit the close-prompt (below). Do **not** write to Jira. Do **not**
+open a planning doc.
+
+## Output template
+
+Frozen per Q25 (see
+[`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md)).
+
+````markdown
+## Refined ticket
+
+**Title:** <rewritten title>
+
+<rewritten description — tightened AC, explicit out-of-scope,
+open questions surfaced>
+
+## Top-5 risks
+
+1. <risk> — <mitigation / deferral>
+2. <risk> — <mitigation / deferral>
+3. <risk> — <mitigation / deferral>
+4. <risk> — <mitigation / deferral>
+5. <risk> — <mitigation / deferral>
+
+## Persona voices
+
+- **Developer** — <one paragraph>
+- **Senior Engineer** — <one paragraph>
+- **Product Owner** — <one paragraph>
+- **Stakeholder** — <one paragraph>
+- **Critical Challenger** — <one paragraph>
+- **AI Agent** — <one paragraph>
+- **[qa]** — *(only when `--personas=+qa`)* <one paragraph>
+
+## Orchestration notes
+
+- `validate-feature-fit` — <fired / skipped; key findings or "clean">
+- `threat-modeling` — <fired / skipped; key findings or "clean">
+- Repo-aware — <on / off; contexts loaded>
+````
+
+The "Refined ticket" section is wrapped in a **copyable Markdown box**
+so the user can grab it verbatim.
+
+## Close-prompt (mandatory final step)
+
+**Probe write access first (Phase F6).** Cheap upfront check before
+rendering:
+
+```python
+from scripts.refine_ticket_detect import render_close_prompt
+
+try:
+    me     = jira_get("/myself")               # existence → auth works
+    meta   = jira_get(f"/issue/{key}/editmeta")# fields → write access
+    write  = bool(meta.get("fields"))
+except Exception:
+    write = None                                # probe itself failed
+
+print(render_close_prompt(write))
+```
+
+Behaviour:
+
+| Probe result | Prompt shape |
+|---|---|
+| Write access present (`True`) | Full three-option prompt (comment / replace / nothing) |
+| Read-only (`False`) | Single option: *"Copy-paste — no write access to this project"* |
+| Probe failed (`None`) | Full three-option prompt; skill degrades to copy-paste on selection (v1 fallback) |
+
+Per user interaction rules, accept number or free text. `editmeta`
+is cheap and cacheable; cache per Jira project key for the session,
+re-probe on project change.
+
+## Output format
+
+1. **Refined ticket** section with rewritten title + description, wrapped in a copyable markdown block.
+2. **Top-5 risks** as a numbered list, each item paired with a mitigation or deferral.
+3. **Persona voices** — one paragraph per persona from the active set; no skipped personas without explicit reason.
+4. **Orchestration notes** naming every sub-skill that fired or was skipped, with a one-line reason.
+5. **Close-prompt** with exactly three numbered options (comment / replace / nothing); no fourth option in v1.
+
+## Gotcha
+
+- The model tends to invent risks that sound plausible but aren't anchored in the ticket text. Every risk in Top-5 must cite a phrase, AC bullet, or sub-skill finding — no hypotheticals.
+- Persona voices degrade into generic platitudes when the ticket is already tight. If a persona has nothing real to flag, write one sentence stating that — do not pad.
+- Sub-skills (`validate-feature-fit`, `threat-modeling`) cost tokens; orchestrate only when the trigger matrix actually matches, not defensively on every run.
+- Branch-detection matches the first `[A-Z]+-[0-9]+` in the branch name; chained keys (e.g. `feat/PROJ-1-and-PROJ-2`) pick the first and note the rest.
+
+## Do NOT
+
+- Do NOT write back to Jira in v1 — output is copyable markdown; write-back is user-gated via the close-prompt.
+- Do NOT chain into `/estimate-ticket` or `/feature-plan` automatically — separate invocations by design (Q5 decision).
+- Do NOT duplicate logic from `validate-feature-fit` or `threat-modeling` — orchestrate by reference, cite findings, don't re-derive them.
+- Do NOT skip the close-prompt, even when the ticket looks fine and the user seems eager to move on — the prompt is the contract.
+- Do NOT emit persona voices outside the active set; if the user passed `--personas=+qa`, add QA, otherwise do not.
+
+## See also
+
+- [`jira-ticket`](../../commands/jira-ticket.md) — ticket loader
+- [`validate-feature-fit`](../validate-feature-fit/SKILL.md) — orchestrated sub-skill
+- [`threat-modeling`](../threat-modeling/SKILL.md) — orchestrated sub-skill
+- [`feature-explore`](../../commands/feature-explore.md) — upstream idea capture; hints at `/refine-ticket` when input looks like a ticket
+- [`feature-plan`](../../commands/feature-plan.md) — downstream planning
+- [`adversarial-review`](../adversarial-review/SKILL.md) — same `critical-challenger` persona, different stage (post-plan)
+- [`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap
+- [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it

package/.agent-src/skills/refine-ticket/detection-map.yml

@@ -0,0 +1,124 @@
+# Detection map for refine-ticket orchestration
+#
+# Declares which sub-skills fire on which ticket-body signals.
+# Consumed by:
+#   - scripts/refine_ticket_detect.py  (deterministic helper, pytest-covered)
+#   - the refine-ticket skill's Step 2  (cites this file, never re-derives)
+#
+# Schema:
+#   sub_skills:
+#     <skill-name>:
+#       description: one-line reason this skill should fire
+#       keywords: [list of case-insensitive substring signals]
+#       require_count: int  (minimum distinct matches to fire; default 1)
+#       regex: [list of python-compatible regex; any match counts as 1]
+#       notes: free text — visible in the orchestration-notes output
+#       alternative_signals:       (Phase F3, optional)
+#         min_distinct_ac_first_words: int   # scope-creep proxy
+#         min_body_sentences: int            # sprawl-in-prose proxy
+
+version: 1
+
+sub_skills:
+  validate-feature-fit:
+    description: >
+      Ticket body mentions multiple existing feature names — potential
+      duplicate or scope-creep signal.
+    require_count: 2
+    # Feature names are repo-specific; the default list covers common
+    # product areas. Projects can extend via agents/overrides/ or by
+    # editing a project-local copy of this file.
+    keywords:
+      - dashboard
+      - billing
+      - subscription
+      - onboarding
+      - notifications
+      - reporting
+      - export
+      - import
+      - audit log
+      - integration
+      - api
+      - webhook
+      - user management
+      - permissions
+      - roles
+      - invoicing
+      - admin
+    alternative_signals:
+      # Phase F3 — scope-creep / prose-sprawl safety net. Thresholds
+      # calibrated on existing fixtures so current behaviour does not
+      # regress: clean.md (2 sentences / 5 AC first-words) and
+      # duplicate_intent.md (3 / 3) stay below the bar; a dedicated
+      # scope_creep_prose.md fixture sits above it.
+      min_distinct_ac_first_words: 7
+      min_body_sentences: 6
+    notes: >
+      Matches count distinct keywords — if two or more different feature
+      names appear in the ticket, validate-feature-fit fires. Single-
+      keyword tickets skip this sub-skill, unless the alt-signal
+      thresholds catch a scope-creep pattern (many distinct AC first-
+      words or a sprawling description body).
+
+  threat-modeling:
+    description: >
+      Ticket touches auth / data-sensitivity / trust-boundary surfaces —
+      pre-implementation threat model required.
+    require_count: 1
+    keywords:
+      - auth
+      - authentication
+      - authorization
+      - login
+      - logout
+      - password
+      - token
+      - jwt
+      - oauth
+      - session
+      - webhook
+      - upload
+      - file upload
+      - queue
+      - queued job
+      - worker
+      - secret
+      - secrets
+      - api key
+      - tenant
+      - tenancy
+      - multi-tenant
+      - admin
+      - admin-only
+      - pii
+      - personal data
+      - gdpr
+      - public endpoint
+      - public api
+      - billing
+      - payment
+      - invoice
+      - stripe
+      - paypal
+    regex:
+      - '\bCVE-\d{4}-\d+\b'
+    notes: >
+      Single-keyword match fires; threat-modeling is cheap and
+      security-sensitive tickets are expensive to re-visit post-ship.
+
+repo_aware:
+  description: >
+    When invoked inside a repo clone, /refine-ticket loads
+    agents/contexts/ for domain vocabulary and scans recent branches /
+    commits for naming conventions. Outside a repo, skip silently.
+  signals:
+    - path: .git
+      type: dir
+    - path: agents/contexts
+      type: dir
+    - path: composer.json
+      type: file
+    - path: package.json
+      type: file
+  require_count: 1

package/.agent-src/skills/refine-ticket/evals/output-schema.yml

@@ -0,0 +1,16 @@
+# Output-schema contract for `refine-ticket`.
+#
+# Locks the frozen three-section shape of the `## Output template`
+# block so refactors cannot silently drift the output away from what
+# consumers copy-paste into Jira. Enforced by `scripts/skill_linter.py`
+# (`lint_output_schema`) — a drift is a hard error.
+#
+# Governed by: road-to-trigger-evals.md Phase 3.5 (originally deferred
+# from archive/road-to-ticket-refinement.md Phase 1 per Q26).
+
+version: 1
+
+required_headers:
+  - "Refined ticket"
+  - "Top-5 risks"
+  - "Persona voices"

package/.agent-src/skills/refine-ticket/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "refine-ticket",
+  "description": "5 should-trigger + 5 should-not-trigger queries. Should-trigger covers DE + EN phrasings and the four input paths (key, branch, paste, URL). Should-not-trigger covers the four near-miss neighbors (plan / estimate / duplicate / threat-model / bug-investigate) whose vocabulary overlaps with ticket refinement.",
+  "queries": [
+    {"q": "refine this ticket before I plan it", "trigger": true},
+    {"q": "tighten the AC on PROJ-123", "trigger": true},
+    {"q": "is this ticket ready for planning?", "trigger": true},
+    {"q": "verbessere das Ticket, ist das klar genug?", "trigger": true},
+    {"q": "poke holes in this Jira ticket and rewrite it", "trigger": true},
+    {"q": "plan the feature described in PROJ-123", "trigger": false, "note": "routes to /feature-plan, not refinement"},
+    {"q": "estimate how big PROJ-123 is", "trigger": false, "note": "routes to /estimate-ticket (Phase 4 sibling)"},
+    {"q": "is this feature already implemented somewhere?", "trigger": false, "note": "routes to validate-feature-fit directly"},
+    {"q": "threat-model the webhook endpoint in PROJ-123", "trigger": false, "note": "routes to threat-modeling directly"},
+    {"q": "investigate this bug — I think there's a Sentry issue linked", "trigger": false, "note": "routes to /bug-investigate"}
+  ]
+}

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

@@ -0,0 +1,199 @@
+---
+name: requesting-code-review
+description: "Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'."
+personas:
+  - critical-challenger
+source: package
+---
+
+# requesting-code-review
+
+## 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
+  context-switch smoothly
+* 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
+
+## Goal
+
+Give the reviewer exactly the context they need — what changed, why,
+how to verify — without forcing them to reconstruct your thought
+process. A well-framed review request **halves** review time and
+**reduces** back-and-forth on missing context.
+
+## The Iron Law
+
+```
+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.
+
+## Procedure
+
+### 1. Self-review first
+
+Before asking anyone else:
+
+* Read the full diff (`git diff <base>...<head>`), not just 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
+
+Use [`review-changes`](../../commands/review-changes.md) as the
+structured walk-through.
+
+### 2. Establish the diff baseline
+
+Determine the correct base commit:
+
+```bash
+# Simple branch from main
+BASE=$(git merge-base HEAD main)
+
+# Stacked PR — parent branch is base, not main
+BASE=$(git merge-base HEAD <parent-branch>)
+
+HEAD=$(git rev-parse HEAD)
+```
+
+The base matters for the reviewer's diff view — wrong base = they
+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.
+
+| Question | Where it lives |
+|---|---|
+| **What changed?** | PR title (imperative, Conventional Commits) + summary bullets |
+| **Why?** | Link to ticket / issue / Sentry event / user message |
+| **How do I verify it?** | Test plan: commands to run, URLs to hit, expected behavior |
+| **What should I look at first?** | Highlights: "pay attention to X because Y" or "skip Z, it is generated" |
+
+See [`create-pr-description`](../../commands/create-pr-description.md)
+for the full structured template, and
+[`conventional-commits-writing`](../conventional-commits-writing/SKILL.md)
+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
+
+### 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
+* **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.
+
+### 6. Send and wait — do not nudge early
+
+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
+
+When review comments arrive → switch to
+[`receiving-code-review`](../receiving-code-review/SKILL.md).
+
+## Output format
+
+When handing the review request to the reviewer (PR body, Slack, email):
+
+1. **Title** — Conventional Commit imperative
+2. **Summary** — 2–5 bullets of what changed
+3. **Motivation** — why, with ticket / Sentry / user-message link
+4. **Test plan** — exact commands or URLs + expected result
+5. **Risk / scope notes** — what the reviewer should pay attention to
+6. **Non-goals** — what this PR deliberately does **not** do
+7. **Screenshots / logs** — when UI or runtime behavior changed
+
+## Gotchas
+
+* "Ready for review" on a red CI run signals carelessness — wait for
+  green or explain the specific failure
+* 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 —
+  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
+* Rebasing during review invalidates line-comments; let reviewers
+  finish a round before rebasing when possible
+
+## Do NOT
+
+* Do NOT request review before self-review
+* Do NOT request review on a branch with failing CI (except when
+  explicitly documenting "CI broken, please eyeball X only")
+* Do NOT mix unrelated changes in one PR
+* Do NOT force-push during active review without a good reason and a
+  note to the reviewer
+* Do NOT leave the PR description empty
+* Do NOT request review from reviewers who lack context just to get
+  approvals
+
+## Anti-patterns
+
+* "Small cleanup" titles on 800-line diffs
+* Test plan that says "should work"
+* Hiding a risky change inside a 40-file refactor PR
+* Pinging reviewers before CI goes green
+* Requesting review as a substitute for thinking the problem through
+
+## When to hand over to another skill / command
+
+* Self-review walkthrough → [`review-changes`](../../commands/review-changes.md)
+* Bringing a stacked branch up to date first →
+  [`prepare-for-review`](../../commands/prepare-for-review.md)
+* Writing the PR description → [`create-pr-description`](../../commands/create-pr-description.md)
+* Actually opening the PR → [`create-pr`](../../commands/create-pr.md)
+* Writing the commits themselves → [`commit`](../../commands/commit.md),
+  [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md)
+* Verifying readiness → [`verify-before-complete`](../verify-before-complete/SKILL.md)
+* Processing the feedback when it arrives → [`receiving-code-review`](../receiving-code-review/SKILL.md)
+
+## Validation checklist
+
+Before asking for review:
+
+* [ ] Self-review walkthrough done on the full diff
+* [ ] Linter + targeted tests + full test suite green
+* [ ] PR title follows Conventional Commits
+* [ ] PR description has summary, motivation, test plan, risk notes
+* [ ] Diff is reviewable in size (split if > 400 lines of real code)
+* [ ] CODEOWNERS / reviewer set is correct
+* [ ] No debug code, secrets, or stray files in the diff
+* [ ] No unrelated changes bundled in