@event4u/agent-config 1.34.0 → 1.36.0

package/.agent-src/skills/customer-research/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: customer-research
+description: "Use when shaping a discovery slice — JTBD-framed interview guide, switch-event focus, verbatim quotes not summaries. Triggers on 'talk to users', 'why did they cancel', 'before we build X'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product]
+---
+
+# customer-research
+
+## When to use
+
+- A backlog item is fuzzy because no one has talked to a current user about the underlying job in the last quarter.
+- A churn or refund spike needs a switch-event explanation, not a feature gap list.
+- A product owner is about to write AC for a feature that has not been validated against a real user job.
+
+Do NOT use for quantitative funnel diagnosis (see `funnel-analysis`),
+RICE-style ranking (see `rice-prioritization`), or surveying at scale —
+this skill is about depth-5-to-10 interviews, not statistics.
+
+## Cognition cluster
+
+- **Mental model 2 — Jobs-to-be-Done.** Frames every question against
+  the **switch event**: what caused the user to fire the previous
+  solution? See [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 2.
+- **Mental model 3 — Pareto principle.** A research week that
+  produces 12 distinct insights is usually re-discovering the same
+  three. See `mental-models.md` § 3.
+
+## Procedure
+
+### Step 0: Frame the job
+
+1. Write one sentence: *"Users hire \<thing\> to make progress in \<situation\>, when motivated by \<pressure\>, expecting \<outcome\>."* If you cannot finish the sentence, the discovery slice is not yet shaped — stop and route to `po-discovery`.
+2. Read the **product** slot of the [context-spine](../../../docs/contracts/context-spine.md) (if the consumer project has filled it) for bounded scope, and the **team** slot for the senior PO / researcher handoff target. Skip if absent — note in the brief.
+3. Identify **one** competing solution the user might fire. Multiple competitors per session blurs the switch event.
+
+### Step 1: Recruit the right 5–8
+
+1. Recruit **switchers** (joined in last 60 days) and **leavers**
+   (cancelled in last 60 days). Long-tenure power-users go in a
+   separate bucket — they explain habits, not jobs.
+2. 5 minimum, 8 maximum. Saturation hits around 6 in a tightly
+   scoped job — the Pareto cut. Beyond 8 is research theatre.
+3. Avoid friends, employees, beta-program over-talkers — selection bias is the failure mode that survives the AC.
+
+### Step 2: Run the interview
+
+1. Open with the **switch event**: *"Walk me through the day you decided to start using \<product\>."* Time, place, trigger, alternative considered.
+2. Past behaviour, not hypothetical. Replace *"would you use"* with *"the last time you needed X, what did you do?"*.
+3. Capture **quotes**, not summaries. Verbatim quotes survive the AC; paraphrases get re-interpreted into pre-existing beliefs.
+4. Listen for the **anxiety / habit** pair — what they feared in switching, what habit died.
+
+### Step 3: Code the evidence
+
+1. One quote per insight. Tag each with: switch-event, anxiety, habit, expected-outcome, unexpected-outcome.
+2. An insight without a quote is a hypothesis, not a finding — mark it.
+3. Frequency-rank by how many distinct interviewees touched the insight (≥ 3 is signal; 1 is anecdote).
+
+### Step 4: Hand back
+
+1. Produce the three artifacts (see `## Output`).
+2. Hand the brief to the senior PO. Do **not** translate findings into AC inside this skill — that is `refine-ticket`'s job.
+
+## Related Skills
+
+**WHEN to use this**
+
+- The unit of analysis is **a real user's switch event**.
+- Discovery is fuzzy and the team is about to ship without validation.
+- A retention or churn spike needs a narrative, not a metric.
+
+**WHEN NOT to use this**
+
+- Quantitative drop-off across stages — route to [`funnel-analysis`](../funnel-analysis/SKILL.md).
+- Ranking competing initiatives — route to [`rice-prioritization`](../rice-prioritization/SKILL.md).
+- Reframing a fuzzy product ask before any user contact — route to [`po-discovery`](../po-discovery/SKILL.md).
+- AC sharpening on an already-validated ticket — route to [`refine-ticket`](../refine-ticket/SKILL.md).
+
+## When the agent should load this
+
+- "We need to talk to users before we build X."
+- "Why are people churning at month 2?"
+- "Run customer research on the new pricing tier."
+- "I keep guessing what the user wants — let's actually ask."
+- "Before refining this ticket, do we know the real job?"
+
+## Output
+
+1. **`research-brief.md`** — frame sentence, recruit criteria, target sample, JTBD focal job, list of competing solutions in scope. Pre-interview artifact.
+2. **`evidence-log.md`** — one row per insight: quote · interviewee ID · tag (switch / anxiety / habit / outcome) · frequency. Sorted by frequency descending. Verbatim only.
+3. **`switch-event-summary.md`** — narrative of the dominant switch event(s) the research surfaced, with ≥ 3 supporting quotes per claim. Hand-off artifact for [`refine-ticket`](../refine-ticket/SKILL.md) and the senior product owner persona (currently [`product-owner`](../../personas/product-owner.md); senior persona shipping in next plate).
+
+## Gotcha
+
+- Asking *"would you use"* contaminates the answer with politeness; ground every question in past behaviour.
+- One articulate interviewee can swamp evidence-log. Frequency-rank by distinct people, not distinct quotes.
+- Tagging too aggressively pre-interview hides surprise findings — leave room for `unexpected-outcome`.
+- A research week without ≥ 3 disqualified hypotheses is suspect — research that confirms everything is research that asked nothing.
+
+## Do NOT
+
+- Do NOT translate findings into acceptance criteria inside this skill — hand off to `refine-ticket`.
+- Do NOT recruit only happy users; switchers and leavers carry the switch-event signal, satisfied users do not.
+- Do NOT skip the frame sentence. An unframed interview produces 50 quotes about 8 different jobs.
+
+## Runnable example
+
+Pricing-tier churn at month 2:
+
+- Frame: *"Customers hire \<product\> to make progress in \<weekly reporting\>, motivated by \<board cadence\>, expecting \<one-click roll-up\>."*
+- Recruit: 6 leavers (cancelled within 30 days of month 2), 2 switchers from competitor C.
+- Interview: open with *"Walk me through the day you decided to cancel."* Capture verbatim.
+- Output: `evidence-log.md` shows 5 of 8 cite the *manual export step* as the cancellation trigger — switch-event signal, ≥ 3 frequency. `switch-event-summary.md` recommends the senior PO scope a discovery slice on the export step, not the report itself.

package/.agent-src/skills/decision-record/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: decision-record
 description: "Use when locking a trade-off, structuring an ADR draft, or wiring supersession chains — frames options · trade-offs · consequences before the file is written by `adr-create`."
+status: active
+tier: senior
+source: package
+domain: process
+context_spine: [team]
 personas:
   - senior-engineer
   - critical-challenger
   - product-owner
-source: package
-domain: process
 ---
 
 # decision-record
@@ -37,6 +40,26 @@ Do NOT use when:
 - The user wants a feature plan, not a decision — route to the
   planning command instead.
 
+## Cognition cluster
+
+- **Mental model 4 — Second-order thinking.** Every decision unlocks
+  some futures and locks out others; the consequences block names
+  what becomes harder, not just what becomes easier. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 4.
+- **Mental model 6 — Theory of constraints.** A decision that does
+  not move the binding constraint is theatre; if the trade-off matrix
+  scores every option the same on the constraint that matters, the
+  options are fungible — surface and stop. See `mental-models.md` § 6.
+- **Mental model 10 — Reversible vs irreversible.** Two-way doors
+  get a one-page record; one-way doors get the full options +
+  consequences + supersession chain. The reversibility row of the
+  matrix decides which template fires. See `mental-models.md` § 10.
+- **Team context-spine slot.** Read the **team** slot of the
+  [context-spine](../../../docs/contracts/context-spine.md) to
+  capture who is bound by the decision (review groups, on-call
+  rotation). Skip if the consumer project has not filled it; note in
+  the record.
+
 ## Procedure
 
 ### 1. State the decision in one sentence
@@ -93,7 +116,39 @@ If this decision overrides a prior ADR:
 Output the structured payload (below). The user — or
 `adr-create` — turns it into the file.
 
-## Output format
+## Related Skills
+
+**WHEN to use this**
+
+- The team is about to lock a non-trivial choice and the trade-offs
+  need to survive the conversation that produced them.
+- A prior ADR is being overridden and the supersession chain needs
+  explicit "what changed in the world" rationale.
+- A planning thread has surfaced ≥ 2 viable options and silence is
+  about to pick one by attrition.
+
+**WHEN NOT to use this**
+
+- The choice splits stakeholders along role lines (PO vs ops, eng vs
+  support) — start with [`stakeholder-tradeoff`](../stakeholder-tradeoff/SKILL.md);
+  this skill locks the choice **after** the human cost is mapped.
+- The output is the ADR file itself (numbering, index regen) — route
+  to [`adr-create`](../adr-create/SKILL.md); this skill produces the
+  payload, not the file.
+- The risk shape is the dominant question — route to
+  [`risk-officer`](../risk-officer/SKILL.md) first, then return.
+- The decision is reversible and cheap — write a one-line note and
+  move on; ADRs are for irreversible or expensive constraints.
+
+## When the agent should load this
+
+- "Lass uns das festzurren."
+- "Welche Option ziehen wir und warum?"
+- "Wir müssen ein ADR draus machen."
+- "Trade-off-Matrix für X vs Y."
+- "Diese Entscheidung überschreibt das alte ADR-NN."
+
+## Output
 
 ```
 Decision: <one sentence>
@@ -141,3 +196,23 @@ Next: /adr-create  with the payload above
 - Do NOT pad option counts to look thorough; two real options beat
   four straw men.
 - Do NOT silently update an old ADR; supersession is explicit.
+
+## Runnable example
+
+Replacing the in-house cron runner with a managed scheduler:
+
+- Decision: *"We need to decide between keeping the in-house cron
+  runner and migrating to the managed scheduler because the on-call
+  rotation has paged on missed-run incidents three times in 60 days."*
+- Options: (1) keep in-house + add monitoring; (2) migrate to
+  managed scheduler; (3) do nothing.
+- Matrix rows that **separate** options: implementation cost,
+  operational load, blast radius on outage, reversibility.
+- Locked: *"We pick the managed scheduler."*
+- Consequences: `+` on-call gets paged on scheduler infra, not
+  application code. `–` job definitions move to a vendor format,
+  raising migration cost if we leave. `✗` we cannot run jobs in the
+  app process anymore — assumes vendor uptime.
+- Supersedes: ADR-014 *"in-house cron runner"*; trigger = three
+  missed-run pages in 60 days now exceed the SLO budget.
+- Next: `/adr-create` with the payload, append `supersedes: ADR-014`.

package/.agent-src/skills/discovery-interview/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: discovery-interview
+description: "Use when running discovery interviews — question-bank build, bias audit, insight extraction. Triggers on 'audit my guide', 'extract insights from transcript', 'is my hypothesis falsifiable'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product]
+---
+
+# discovery-interview
+
+## When to use
+
+- A discovery slice has been framed (`customer-research` ran), but the interview guide is still rough or untested.
+- A transcript exists and the team needs structured insight extraction, not narrative summary.
+- An interview round produced surprising findings; a bias audit is needed before the team acts on them.
+
+Do NOT use for the upstream framing of the discovery slice (frame
+sentence, recruit criteria, JTBD focal job) — that is
+[`customer-research`](../customer-research/SKILL.md). Do NOT use for
+quantitative survey design or scale-bound research.
+
+## Cognition cluster
+
+- **Mental model 22 — Data-informed, not data-driven.** Interview
+  data is signal at low N; treat it as evidence to reason with, not
+  a vote count. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 22.
+- **Mental model 15 — Signal vs noise.** A vivid quote from one
+  articulate user can swamp three muted but consistent signals;
+  frequency-rank by distinct people, never by quote count. See
+  `mental-models.md` § 15.
+- **Mental model 28 — Eisenhower matrix.** Sort post-interview
+  insights into urgent / important quadrants so the team acts on
+  high-importance signals, not the loudest ones. See
+  `mental-models.md` § 28.
+- **Product context-spine slot.** Read **product** for the focal job
+  + competitor names; do **not** re-derive these inside this skill.
+  See [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### 1. Build the question bank
+
+1. Anchor on the **switch event** from `customer-research`. The
+   first question is always *"Walk me through the day you decided
+   to ..."* — never *"would you ..."*.
+2. Three layers:
+   - **Past behaviour** (what did you do? when? alternative considered?)
+   - **Anxiety / habit** (what feared in switching? what habit died?)
+   - **Outcome** (what changed for you? expected? unexpected?)
+3. Cap at 8 open questions per 45-min slot. Beyond that, the
+   interview becomes a survey delivered in person.
+
+### 2. Audit the bank for bias
+
+Before running, inspect each question and review the bank against the
+four common biases:
+
+- **Leading** — *"Don't you think X is annoying?"* → rewrite as past
+  behaviour.
+- **Hypothetical** — *"Would you use Y?"* → replace with *"Last
+  time you needed Y, what did you do?"*.
+- **Confirmation** — every question presupposes the team's hypothesis
+  is correct. At least two questions must be able to **disconfirm** it.
+- **Recall ceiling** — questions that ask for events ≥ 90 days back
+  produce confabulation; bound the timeframe.
+
+A bank that survives the audit unchanged is suspect — re-read.
+
+### 3. Run-time discipline
+
+1. Open with the switch event. Stay silent for 8 seconds after the
+   user finishes; the second answer is usually the truer one.
+2. Capture verbatim, not paraphrase. *"It made me anxious"* is data;
+   *"the user expressed concern"* is interpretation.
+3. Probe with *"tell me more about X"* on any anxiety / habit
+   mention; do not switch topics until the thread is exhausted.
+
+### 4. Extract insights
+
+For each transcript:
+
+1. One quote per insight. Tag: switch / anxiety / habit /
+   expected-outcome / unexpected-outcome / disconfirmation.
+2. Frequency-rank by distinct interviewees (≥ 3 = signal; 1 = anecdote).
+3. Mark **disconfirmations** explicitly — these are the most
+   valuable rows, because they are the cheapest to ignore.
+
+### 5. Hand back
+
+Produce the three artifacts (see `## Output`); hand the disconfirmation
+log to whoever owns the original hypothesis.
+
+## Related Skills
+
+**WHEN to use this**
+
+- The discovery slice is framed and the interview guide / transcript
+  is the unit of work.
+- A round of interviews ran and the insights need structured extraction
+  (frequency-ranked, bias-audited, disconfirmations highlighted).
+
+**WHEN NOT to use this**
+
+- The slice itself is unframed — start with
+  [`customer-research`](../customer-research/SKILL.md); this skill
+  inherits its frame, never re-derives it.
+- The signal needs to come from existing artefacts (issues, PRs, errors)
+  rather than a live interview — route to [`voc-extract`](../voc-extract/SKILL.md).
+- Insights translate into AC for a ticket — hand off to
+  [`refine-ticket`](../refine-ticket/SKILL.md).
+- The output is a quantitative funnel — route to
+  [`funnel-analysis`](../funnel-analysis/SKILL.md).
+
+## When the agent should load this
+
+- "Hilf mir den Interview-Leitfaden auditieren."
+- "Welche Fragen sind biased?"
+- "Extract die Insights aus diesem Transkript."
+- "Wir haben 6 Interviews geführt — was ist Signal, was ist Anekdote?"
+- "Ist meine Hypothese widerlegbar mit dem aktuellen Frageset?"
+
+## Output
+
+1. **`question-bank.md`** — 8 open questions, each tagged
+   past-behaviour / anxiety-habit / outcome; bias-audit notes per
+   rewritten question.
+2. **`insight-log.md`** — one row per insight: quote · interviewee
+   ID · tag · distinct-people frequency. Sorted descending. Verbatim.
+3. **`disconfirmation-log.md`** — each row names the original
+   hypothesis, the interview-derived disconfirmation, and the named
+   owner who must respond before the team acts on the round.
+
+## Gotcha
+
+- A bank that survived the audit unchanged is rare; usually means
+  the audit was rushed, not that the bank was perfect.
+- One articulate interviewee biases insight-extraction toward their
+  vocabulary — frequency-rank by people, not quotes.
+- Disconfirmations are the cheapest insight to ignore and the most
+  valuable to act on; the log exists so they survive the round.
+
+## Do NOT
+
+- Do NOT re-derive the frame inside this skill — read the **product**
+  spine slot or hand back to `customer-research`.
+- Do NOT translate insights into AC inside this skill — that is
+  `refine-ticket`.
+- Do NOT collapse disconfirmations into "we also heard X" prose;
+  they earn their own log.

package/.agent-src/skills/launch-readiness/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: launch-readiness
+description: "Use before merging a release-shaped PR — pre-merge checklist, rollout plan, rollback criteria, ops handoff. Triggers on 'ready to ship', 'launch checklist', 'rollout plan for X'."
+status: active
+tier: senior
+source: package
+domain: process
+context_spine: [team, product]
+---
+
+# launch-readiness
+
+## When to use
+
+- A change is about to merge that crosses a release boundary (new feature on `main`, version bump, public-facing comms attached).
+- An ops handoff is implied — the on-call rotation, support team, or downstream consumers need to know.
+- A rollback criterion has not been written down yet.
+
+Do NOT use for routine internal merges
+([`finishing-a-development-branch`](../finishing-a-development-branch/SKILL.md))
+or for the comms text itself ([`release-comms`](../release-comms/SKILL.md)).
+This skill produces the **decision** to ship and the rollback contract.
+
+## Cognition cluster
+
+- **Mental model 10 — Reversible vs irreversible.** Map every step
+  of the rollout to a reversibility class; the rollback criteria
+  must name the irreversible steps and the abort threshold for each.
+  See [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 10.
+- **Mental model 29 — Pre-mortems.** Imagine the rollout failed in
+  six hours; what failed first? The pre-mortem becomes the rollback
+  criteria, not a separate document. See `mental-models.md` § 29.
+- **Mental model 4 — Second-order thinking.** Enumerate what
+  becomes harder *after* the launch (rollback cost, contributor
+  ergonomics, doc churn). See `mental-models.md` § 4.
+- **Team + product context-spine slots.** Read **team** for the
+  on-call rotation and ops handoff path; read **product** for the
+  segment / cohort exposure of the rollout. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### 1. Identify the launch shape
+
+One sentence: *"This change ships **X** to **segment Y** behind
+**rollout mechanism Z**."* If you cannot, the change is not
+release-shaped; route to `finishing-a-development-branch`.
+
+### 2. Inspect the pre-merge checklist
+
+Walk the diff with the following gates:
+
+- Tests green on the integration suite (cite the run).
+- Quality gates green (PHPStan / linters / type-checks).
+- Migrations are reversible OR the irreversibility is explicit.
+- Feature flag / kill switch named, default off unless intended.
+- Doc / changelog / release notes present (hand off to
+  [`release-comms`](../release-comms/SKILL.md) for the prose).
+- Rollback path tested at least mentally; named in step 4.
+
+Cells without evidence block the launch — surface, do not
+hand-wave.
+
+### 3. Plan the rollout
+
+- **Mechanism** — flag, canary cohort, blue-green, immediate.
+- **Order** — internal → trusted segment → general; cite the
+  segment per stage from the **product** spine slot.
+- **Telemetry** — the metric that **proves** rollout health.
+- **Owner** — named role per stage (not name); from the **team**
+  spine slot.
+
+### 4. Write rollback criteria
+
+For each stage:
+
+- **Trip wire** — the metric value that fires rollback.
+- **Decision window** — how long the trip wire must hold.
+- **Abort path** — what the on-call does (revert PR, flip flag,
+  drain queue), pre-rehearsed.
+- **Irreversible steps** — explicit list; if any irreversible step
+  is in scope, the launch needs a written sign-off, not implicit.
+
+Pre-mortem rule: every trip wire must answer *"what would have
+caused this in six hours?"* If you cannot, the trip wire is wrong.
+
+### 5. Ops handoff
+
+- Who is paged on which alert (from **team** spine slot).
+- Where the rollback runbook lives (link).
+- Date / time of the handoff conversation; sign-off from the
+  receiving role.
+
+### 6. Hand back
+
+Hand the artefact below to whoever requested the launch decision;
+route comms to [`release-comms`](../release-comms/SKILL.md) and
+post-launch metrics tracking to the team's monitoring stack.
+
+## Related Skills
+
+**WHEN to use this**
+
+- A release-shaped PR is about to merge.
+- Rollback criteria need to land in writing before the merge button
+  is pressed.
+- Ops handoff is implied and not yet executed.
+
+**WHEN NOT to use this**
+
+- The change is internal and routine — route to
+  [`finishing-a-development-branch`](../finishing-a-development-branch/SKILL.md).
+- The output is the public comms — route to
+  [`release-comms`](../release-comms/SKILL.md).
+- The rollout decision involves stakeholder conflict — route to
+  [`stakeholder-tradeoff`](../stakeholder-tradeoff/SKILL.md) first.
+- The decision is reversible-and-cheap — write a one-line note,
+  skip the full artefact.
+
+## When the agent should load this
+
+- "Sind wir launch-ready?"
+- "Bau mir die Rollback-Kriterien für Phase X."
+- "Ops-Handoff für die Release morgen."
+- "Was bricht, wenn wir den Flag flippen?"
+- "Pre-merge-Checklist für PR #N."
+
+## Output
+
+1. **Launch shape** — one-sentence statement of the change.
+2. **Pre-merge checklist** — gate · status · evidence (citation).
+3. **Rollout plan** — stages × mechanism · order · telemetry · owner.
+4. **Rollback contract** — per stage: trip wire · decision window ·
+   abort path · irreversible steps.
+5. **Ops handoff** — pager mapping · runbook link · sign-off.
+6. **Outstanding** — anything blocking the launch; explicit, not
+   collapsed.
+
+## Gotcha
+
+- A checklist with all green and no citations is theatre; every
+  green needs an artefact.
+- A trip wire without a decision window is unactionable — *"if
+  errors spike"* is not a trigger; *"5xx > 2% for 10 min"* is.
+- Irreversible steps without written sign-off are the most common
+  post-mortem ancestor — surface, do not skip.
+
+## Do NOT
+
+- Do NOT write the comms text here — that is `release-comms`.
+- Do NOT lock the rollback contract verbally — it lives in the
+  output block, citable.
+- Do NOT let any stage own itself — every stage names a role from
+  the **team** spine slot.
+- Do NOT hand the artefact to a receiver who has not signed off on
+  ops handoff.