@event4u/agent-config 5.10.1 → 6.1.0

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

@@ -0,0 +1,291 @@
+---
+model_tier: inherit
+name: "refine-prompt"
+description: "Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'."
+personas:
+  - developer
+  - senior-engineer
+  - ai-agent
+domain: product
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Refine Prompt
+
+> Move a free-form prompt from "raw text" to "engine-ready" in one run.
+> Produces reconstructed acceptance criteria, explicit assumptions,
+> and a confidence band that decides whether the engine proceeds
+> silently, halts for confirmation, or refuses to plan.
+>
+> Sibling of [`refine-ticket`](../refine-ticket/SKILL.md) — same
+> reconstruction-of-intent pattern, different input shape. Tickets
+> arrive structured (id, title, AC); prompts arrive as one string.
+
+## When to use
+
+- The user invokes `/work "<prompt>"` or pastes a free-form request.
+- The dispatcher hits `input.kind="prompt"` in the `refine` step.
+- A prompt looks ambiguous, broad, or scope-undefined and the user
+  asks "ist das klar genug, um loszulegen?".
+- Before any plan/apply step on prompt-driven work — never after.
+
+## When NOT to use (near-misses)
+
+| Phrasing | Route to |
+|---|---|
+| "refine this ticket" | [`refine-ticket`](../refine-ticket/SKILL.md) |
+| "estimate this prompt" | not supported — score then estimate downstream |
+| "plan this feature" | `/feature-plan` (downstream) |
+| "is this a duplicate?" | `validate-feature-fit` (sub-skill, post-refine) |
+
+`refine-prompt` is the *first* gate on prompt-driven flow. It does not
+plan, does not implement, does not write back anywhere.
+
+## Input
+
+Exactly one path: a non-empty raw string carried in
+`state.input.data.raw` (built by [`work_engine.resolvers.prompt`](../../templates/scripts/work_engine/resolvers/prompt.py)).
+No branch detection, no URL parsing, no clipboard fallback — the
+calling command (`/work`) owns prompt capture; this skill only refines.
+
+If `raw` is missing, empty, or whitespace-only the resolver already
+raised `PromptResolverError`. The skill never receives that input.
+
+## Modes and bypass
+
+The skill honours `prompt_optimization.inbound` (or
+`prompt_optimization.default` when no inbound override is set) from
+`.agent-project-settings.yml` / `.agent-settings.yml`. Three modes:
+
+| Mode | Behaviour |
+|---|---|
+| `off` | The skill is a no-op. The dispatcher writes `confidence={"band":"high","score":1.0}` directly and the engine proceeds with the literal prompt. No assumption inference, no clarifying questions. |
+| `mini` | Stack-aware light shaping. Steps 1-2 run; step 3 only emits `assumes:` lines for *implicit stack constraints* (framework, package manager) detected from config files. Steps 4-5 produce 3 AC bullets max. Low-band halts ask at most one question; medium-band halts are auto-confirmed silently. |
+| `max` *(default)* | Full procedure — every step 1–6 runs. Medium-band halts surface the assumption list verbatim; low-band halts ask one clarifying question. This is the existing behaviour. |
+
+**Bypass prefix.** If the raw prompt starts with the configured
+`prompt_optimization.bypass_prefix` (default `/raw`), the skill
+becomes a no-op regardless of mode. The dispatcher strips the
+prefix, passes the remainder through verbatim, and records
+`bypass:true` in the envelope so downstream surfaces (delivery
+report, `--no-prose-synthesis`) can attribute the skip.
+
+```
+/raw migrate auth.service.ts to use jose, keep the API shape
+```
+
+`/raw` is reserved at the prompt boundary only — it has no meaning
+mid-prompt and is not stripped when it appears inside the body.
+
+### Stack-config read (mini / max only)
+
+When the mode is `mini` or `max`, step 3 may read these config files
+(read-only, scope-locked) to enrich the `assumes:` block:
+
+- `package.json` — JS / TS framework detection (Next.js App vs Pages,
+  Remix, SvelteKit, Astro, Expo, …)
+- `composer.json` — PHP framework detection (Laravel, Symfony,
+  framework-less)
+- `pyproject.toml` / `requirements.txt` — Python framework detection
+- `CLAUDE.md` / `AGENTS.md` — project-declared stack hints
+- `.cursorrules` — project-declared stack hints
+- `tsconfig.json` — TS path-alias / module-resolution hints
+
+The skill MUST NOT read source files, `.env*`, secrets, or user
+data. Detection lands as a single `assumes: stack=<framework>@<version>`
+line; the medium-band halt is the user's chance to flip it.
+
+## Procedure
+
+### 1. Read and analyze the prompt
+
+Examine the raw text top to bottom *before* changing anything in
+state. Identify the *single* desired outcome in one sentence —
+verb + object + observable result. If the prompt names two
+unrelated outcomes (e.g. "fix login AND refactor the dashboard"),
+record both but flag scope-overload in step 5; the score will
+land in `medium` or `low`.
+
+This is an analysis pass, not an execution pass. The skill does
+not modify the prompt, infer code changes, or call any tool — it
+investigates the input and produces a structured envelope the
+dispatcher reads.
+
+### 2. Enumerate explicit constraints
+
+Pull every concrete signal from the prompt verbatim:
+
+- **Files / modules** named in the text (`UserController`,
+  `auth.service.ts`, `migrations/2024_…`).
+- **Behaviour anchors** — endpoints, routes, commands, fixtures.
+- **Hard rules** — "must not break X", "without changing the API",
+  "keep backwards compat".
+
+Constraints come from the prompt only. Inferred constraints belong in
+step 3 (assumptions), never here.
+
+### 3. Infer reasonable assumptions
+
+Anything the prompt implies but does not state. Examples:
+
+- "fix the login bug" → assumes the bug is in the existing `auth/`
+  module (no new auth provider).
+- "add caching" → assumes the project's primary cache driver
+  (per `.agent-settings.yml` / `config/cache.php`).
+- "speed up the export" → assumes "faster" means runtime, not memory.
+
+Each assumption is a single line, prefixed with `assumes:`. The
+medium-band halt surfaces them verbatim — no rewording, no
+explanations.
+
+### 4. Generate the AC list
+
+Three to seven bullet points. Each bullet is observable and
+testable in the project's existing test surface (Pest / Jest /
+pytest / etc.). Avoid:
+
+- "works correctly" / "is fast" / "looks better" (untestable)
+- "no regressions" (the test suite already covers that)
+- "follows best practices" (not an AC)
+
+Anchor each bullet to a constraint from step 2 or an assumption from
+step 3 — never both implicit.
+
+### 5. Score confidence
+
+Delegate to [`scripts.work_engine.scoring.confidence`](../../templates/scripts/work_engine/scoring/confidence.py):
+
+```python
+from work_engine.scoring.confidence import score
+result = score(raw=prompt_raw, ac=reconstructed_ac, assumptions=assumptions)
+# result.band ∈ {"high", "medium", "low"}
+# result.score ∈ [0.0, 1.0]
+# result.dimensions: dict[str, int]   # 0–2 per dimension
+# result.reasons: list[str]            # human-readable rationale
+```
+
+The rubric (5 dimensions × 0–2, sum / 10) and band thresholds
+(`high ≥ 0.8`, `medium 0.5–0.79`, `low < 0.5`) are owned by
+`confidence.py`. Do not re-derive them in prose.
+
+### 6. Self-review (3-scan checklist)
+
+Before emitting the envelope, run these three scans. Each is a fast pass; failure blocks emission.
+
+1. **Spec coverage** — every concrete signal from step 2 (constraints) and step 3 (assumptions) is reflected somewhere in the AC list. Walk the constraint list top-to-bottom; each must anchor at least one AC bullet or appear in the *Assumptions* block.
+2. **Placeholder / TODO scan** — the rendered envelope contains no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings. The literal angle-bracket placeholders in the template (`<one sentence …>`, `<bullet>`) must be replaced with concrete text before emission.
+3. **Type / shape consistency** — every named file, module, route, or command in the AC matches the project's existing conventions. If the prompt names `auth.service.ts` but the codebase uses `AuthService.php`, surface the mismatch in *Assumptions* rather than adopting the prompt's spelling.
+
+Source: adapted from an external reference `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
+## Band-action mapping
+
+The `refine` dispatcher step in `directives/backend/refine.py` reads
+the score and returns one of three outcomes — the skill does not
+decide the action, only produces the inputs.
+
+| Band | Outcome | What the user sees |
+|---|---|---|
+| `high` | `SUCCESS` | Silent proceed; AC + assumptions land in the delivery report |
+| `medium` | `PARTIAL` | Assumptions report halt: numbered list of `assumes:` lines + AC, user confirms or edits |
+| `low` | `BLOCKED` | One clarifying question (per [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) Iron Law) |
+
+## Output format
+
+The skill emits a structured envelope; the dispatcher renders it.
+Required fields, in order:
+
+1. **Goal** — single sentence, verb + object + observable result
+2. **Acceptance criteria** — numbered list, 3–7 entries, each
+   anchored to a step-2 constraint or a step-3 assumption
+3. **Assumptions** — bullet list, each line prefixed `assumes:`
+4. **Confidence** — band + score + per-dimension breakdown from
+   `work_engine.scoring.confidence`
+
+The shape below is the rendered surface for `medium` / `low`
+halts; for `high` the same envelope lands in the delivery report
+without a halt.
+
+````markdown
+## Reconstructed prompt
+
+**Goal:** <one sentence, verb + object + observable result>
+
+**Acceptance criteria:**
+1. <bullet>
+2. <bullet>
+3. <bullet>
+
+**Assumptions:**
+- assumes: <line>
+- assumes: <line>
+
+**Confidence:** medium (0.62) — goal_clarity 2 · scope_boundary 1 · ac_evidence 2 · stack_data 1 · reversibility 0
+````
+
+For `low`, the question replaces the AC list:
+
+```
+> The prompt does not name <missing dimension>.
+>
+> 1. <option that resolves the gap>
+> 2. <alternative resolution>
+> 3. <skip / abandon>
+```
+
+## Gotchas
+
+- The model invents AC that *sound* observable but aren't anchored
+  in the prompt or a concrete file. Every AC must trace to a step-2
+  constraint or a step-3 assumption — no free-floating bullets.
+- Assumptions are not commitments. The medium-band halt is the
+  user's chance to flip them; the skill never asserts an assumption
+  as fact.
+- The scorer is heuristic, not LLM-based. Token count is not a
+  signal — a 200-word prompt can score `low` if the goal is vague,
+  and a 20-word prompt can score `high` if scope is unambiguous.
+- UI-shaped prompts ("redesign the dashboard", "make the form
+  prettier") score `low` on `stack_data` until R3 lands the UI
+  directive set; band-action is a pointer to R3, not a refusal.
+
+## Do NOT
+
+- Do NOT call this skill on `input.kind="ticket"` — that path runs
+  through [`refine-ticket`](../refine-ticket/SKILL.md).
+- Do NOT auto-confirm assumptions on the user's behalf in the
+  medium-band halt. The halt is the contract.
+- Do NOT stack multiple clarifying questions in the low-band halt.
+  Iron Law: one question per turn.
+- Do NOT mutate `state.input.data.raw`. The original prompt stays
+  verbatim for replay; reconstructed output lands in
+  `data.reconstructed_ac` and `data.assumptions`.
+- Do NOT re-derive band thresholds in prose. They live in
+  `confidence.py` and only there.
+- Do NOT read source files, `.env*`, secrets, or arbitrary user
+  files when stack-detecting in mini / max mode. The allowlist
+  above (`package.json`, `composer.json`, `pyproject.toml`,
+  `requirements.txt`, `CLAUDE.md`, `AGENTS.md`, `.cursorrules`,
+  `tsconfig.json`) is exhaustive.
+- Do NOT strip the `bypass_prefix` mid-prompt. The prefix is only
+  recognised at the prompt boundary; matches inside the body stay
+  literal.
+- Do NOT silently rewrite the prompt in `max` mode without
+  surfacing the assumption list on a medium-band halt. The diff
+  is the contract.
+
+## See also
+
+- [`refine-ticket`](../refine-ticket/SKILL.md) — sibling for ticket-shaped input
+- [`prompt-optimizer`](../prompt-optimizer/SKILL.md) — engine-outbound sibling; same `prompt_optimization` setting controls its mode
+- [`work_engine.resolvers.prompt`](../../templates/scripts/work_engine/resolvers/prompt.py) — envelope builder
+- [`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
+- AI Council session: `agents/runtime/council/responses/prompt-master-mini.json` (2026-05-17) — analysis behind the mini/max split and `/raw` bypass <!-- council-ref-allowed: ADR decision trace -->

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

@@ -0,0 +1,338 @@
+---
+model_tier: inherit
+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
+domain: product
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - product
+packs:
+  - product-basic
+trust:
+  level: professional
+install:
+  removable: true
+---
+
+# 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
+
+The refined output's prose language is picked once, up front, and
+applied to every section (refined description, risks, persona voices,
+orchestration notes, close-prompt). Fallback order — first hit wins:
+
+1. **User-message language.** If the latest user message is in
+   German, the entire output is German; if English, English; etc.
+   This 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 — detected from the summary + description.
+3. **`.agent-settings.yml` default.** If both are silent or unclear,
+   fall back to the project default in `.agent-settings.yml`
+   (`personal.language` or equivalent). If that is also missing,
+   default to English.
+
+Quoted identifiers (ticket keys, file paths, command names, code
+snippets) stay in their native form. Only the prose mirrors the
+selected 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 their Linear / Shortcut
+  equivalents). `Task` / `Bug` / `Epic` skip the auto-fetch unless a
+  `parent` link field is already populated — in that case the agent
+  folds explicitly without the issuetype guard.
+- `fold_parent_context()` is idempotent; folding twice with the same
+  parent does not duplicate the block.
+- When the parent fetch fails (404, permission, network), skip the
+  fold and append a line 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
+./agent-config refine-ticket:detect <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/settings/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/settings/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.
+
+````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>
+- **User: <label>** — *(only when `--user-type=<id>`)* <one paragraph
+  citing Daily Workflow / Vocabulary / Operational Constraints /
+  Ticket Red Flags from the loaded user-type>
+
+## 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.
+
+## Self-review (3-scan checklist)
+
+Run these three scans on the rendered output before the close-prompt. Each is a fast pass; failure blocks emission and forces a fix.
+
+1. **Spec coverage** — every AC bullet and constraint from the original ticket (and every parent-AC line surfaced via `fold_parent_context`) is reflected in the rewritten ticket, the Top-5 risks, or the *Open questions* section. Nothing from the input vanishes silently.
+2. **Placeholder / TODO scan** — no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings remain. The angle-bracket placeholders in the template (`<rewritten title>`, `<risk>`, `<one paragraph>`) must be replaced with concrete prose before the close-prompt fires.
+3. **Type / shape consistency** — every module, file, route, or domain term cited in the rewritten ticket and Top-5 risks matches `repo_context.context_docs` and `recent_branches` vocabulary. Invented terms are flagged in *Open questions* or replaced with the project's actual term.
+
+Self-review is mechanical (gaps, leftovers, naming drift); persona voices and orchestration outputs handle reasoning critique. Both run; neither replaces the other.
+
+Source: adapted from an external reference `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
+## Close-prompt (mandatory final step)
+
+**Probe write access first (Phase F6).** Before rendering, do a
+cheap upfront check:
+
+```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 the result 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)
+- [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — this skill was drafted under it