@event4u/agent-config 1.34.0 → 1.36.0

package/.agent-src/skills/memory-consolidation/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: memory-consolidation
+description: "Use when consolidating session signals into curated memory — four-phase loop ORIENT → GATHER → CONSOLIDATE → PRUNE. Triggers on 'mine my sessions', 'consolidate memory', 'review intake signals'."
+status: active
+tier: senior
+source: package
+domain: engineering
+context_spine: [repo]
+---
+
+# memory-consolidation
+
+## When to use
+
+- Intake JSONL has accumulated unreviewed signals and `/memory:load` shows the inline-review block.
+- A pattern recurred across recent sessions (correction, preference, decision, repeat-bug) and is at risk of being forgotten by the next fresh chat.
+- Before closing out a multi-day implementation, capture project-scoped facts so the next agent does not re-discover them.
+
+Do NOT use for one-off code review notes (those belong in PR comments,
+not memory), for user-attribute facts like name or IDE preference (the
+`onboard` flow owns those), or for transient TODOs (use the task list).
+
+## Cognition cluster
+
+- **Mental model 5 — Signal vs. noise.** A consolidation pass that
+  promotes 30 entries from a 50-message session is noise; the Pareto
+  cut is roughly 3–5 promote-worthy signals per cycle. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 5.
+- **Mental model 12 — Defense in depth.** Date-discipline, tag
+  intersection, and per-invocation transcript-access confirmation are
+  three independent guards; any one alone fails open. See § 12.
+
+## Procedure
+
+The loop is four sequential phases. Each phase has one exit gate; do
+not advance until the gate is green.
+
+### Phase 1 — ORIENT (review scope and assess adapter)
+
+1. Confirm scope: which project, which time window, which transcript
+   source. Default window: last 14 days. The agent must read the
+   user's last chat message for an explicit `--since` override before
+   defaulting.
+2. Inspect the current curated state: list files under
+   `agents/memory/` and check the most recent `last_validated`
+   timestamps. Identify which schemas are stale before mining adds
+   noise.
+3. Review the **repo** slot of the [context-spine](../../../docs/contracts/context-spine.md)
+   for project boundaries (modules, owners, sensitive paths). If empty,
+   note the gap in the consolidation report; do not invent.
+4. Resolve the `TranscriptAdapter` for the current host (see Adapter
+   contract below). If no adapter matches, stop and route the user to
+   `/memory:propose` for manual signal entry. Do **not** synthesize.
+
+**Exit gate:** scope, window, adapter all named. If any one is
+missing, stop.
+
+### Phase 2 — GATHER SIGNAL
+
+1. Stream transcript turns through the four signal regex families:
+   - **Correction:** `actually|wrong|stop doing|don't do|that's not what|nicht so`.
+   - **Preference:** `prefer|always|never|standard|i want|ich will`.
+   - **Decision:** `let's go with|decided|we'll use|entschieden`.
+   - **Pattern (recurring):** the same file path or symbol appears in
+     ≥ 3 turns within 24 hours.
+2. For each match, extract a **normalised fact** — strip personal
+   pronouns, IDE chrome, timestamps, and turn-id. The fact must be
+   project-scoped (refers to a file, module, command, or invariant)
+   not user-scoped (refers to *me*, *Matze*, *my IDE*).
+3. Drop user-attribute matches. If the fact cannot survive the
+   normalisation, discard it. The miner is a strict gate.
+
+**Exit gate:** ≤ 5 normalised facts per cycle. More than 5 means the
+miner is too loose; tighten patterns and re-run before promoting.
+
+### Phase 3 — CONSOLIDATE
+
+1. Tag each fact via the schema-routing table:
+
+   | Tag | Schema |
+   |---|---|
+   | `convention` | `agents/memory/conventions.yml` |
+   | `invariant` | `agents/memory/domain-invariants.yml` |
+   | `gotcha` | `agents/memory/operational-gotchas.yml` |
+   | `pattern` | `agents/memory/recurring-patterns.yml` |
+
+   A fact may carry **two** tags; the promoter resolves via tag
+   intersection, not by file extension. See
+   [`docs/contracts/agent-memory-contract.md`](../../../docs/contracts/agent-memory-contract.md)
+   for the curated YAML schemas.
+
+2. Append each fact as one JSONL line to
+   `agents/memory/intake/<primary-tag>.jsonl` with required fields
+   per the contract: `ts`, `type`, `key`, `observation`, `source:
+   agent`, `session_id`, plus the new optional `tags: [<one>, <two>]`.
+3. Default to `--preview` mode: render the JSONL block to stdout and
+   stop. Only `--commit-intake` writes the file.
+
+**Exit gate:** every fact carries ≥ 1 tag and a JSONL-shape that
+validates against the contract.
+
+### Phase 4 — PRUNE & INDEX
+
+1. After promotion (handled by `/memory:promote`, not this skill),
+   archive the consumed JSONL lines into
+   `agents/memory/intake/.archive/YYYY-Www.jsonl` — week-bucketed,
+   not day-bucketed (defeats session-context inference attacks).
+2. If a curated entry's `last_validated` field is older than 90 days
+   AND no signal in the last 30 days touched its `key`, mark it
+   stale in the consolidation report — but do **not** auto-delete.
+   Pruning is a human-confirmed action.
+
+**Exit gate:** report cites ≥ 0 promotions, ≥ 0 stale flags, 0
+auto-deletes.
+
+## TranscriptAdapter contract
+
+The miner is host-agnostic by design. A `TranscriptAdapter` for host
+`X` ships:
+
+- **Discover:** function returning the absolute path(s) of session
+  transcripts for the active project, scoped to the `--since` window.
+  Phase 1 ships the Claude-Code adapter only; absent adapter →
+  `not-supported-on-this-host`.
+- **Iterate:** generator yielding turn objects with `{role, ts,
+  text}`. Adapter strips IDE chrome and tool-call boilerplate before
+  yielding.
+- **Redact:** function applied to every yielded text — drops user
+  names, file paths outside the repo root, and any personal
+  identifier the consumer project lists in
+  `.agent-settings.yml` under `memory.redact_patterns`.
+
+Phase 1 implementation lives in
+`/memory:mine-session` (single host: Claude Code,
+`~/.claude/projects/*/sessions/*.jsonl`). Phase 3 of the
+adoption roadmap adds a second host adapter; the contract above is
+documented now so the second implementation is not a vacuum design.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Intake JSONL has > 10 unreviewed signals.
+- A correction / preference recurred across ≥ 3 sessions.
+- Closing out a multi-day implementation.
+
+**WHEN NOT to use this**
+
+- One-off PR review notes — comment on the PR.
+- User-attribute facts (name, IDE) — those belong to the
+  [`onboard`](../../commands/onboard.md) flow, not curated memory.
+- Transient TODOs — use the task-list tools.
+- A single bug fix that does not generalise — fix the bug, do not
+  memorise it.
+
+## When the agent should load this
+
+- "Mine my recent sessions for memory signals."
+- "Consolidate the intake stream into curated entries."
+- "What did we decide about X across the last week?"
+- "Review unreviewed memory signals before I switch projects."
+- "Run a memory consolidation cycle."
+
+## Output
+
+1. **Consolidation report** — Markdown block printed to stdout: scope
+   (project, window, host), signal counts per class, list of
+   normalised facts with tag and target schema, stale-flag list. No
+   side effects in `--preview` mode.
+2. **Intake JSONL appendix** — only with `--commit-intake`: appended
+   lines to `agents/memory/intake/<tag>.jsonl`. Lines validate
+   against the contract.
+3. **Archive bucket** — only after `/memory:promote` runs and lifts
+   the lines into curated YAML: appends to
+   `agents/memory/intake/.archive/YYYY-Www.jsonl`. Week-bucketed.
+
+## Gotcha
+
+- Mining without `--confirm-transcript-access` reads zero turns and
+  prints an opt-in hint. The flag is per-invocation, not persistent.
+- The miner is a strict gate. > 5 normalised facts per cycle means
+  the regex set is too loose, not that the session was rich.
+- A fact tagged `gotcha + invariant` lands in the `gotcha` JSONL
+  (primary tag); the promoter reads tag intersection to decide the
+  curated YAML target.
+- Date-discipline: the `check_memory.py` linter rejects
+  `yesterday|today|tomorrow|last/next/this week|month|year` in curated
+  YAML without an `YYYY-MM-DD` anchor within ±20 chars. Re-anchor
+  before commit.
+
+## Do NOT
+
+- Do NOT auto-trigger this skill on session end. The flow is manual,
+  per-invocation, and confirmed.
+- Do NOT vendor patterns or text from `grandamenium/dream-skill` —
+  the upstream lacks a `LICENSE`. Concept and procedure structure are
+  the only adoption surface.
+- Do NOT promote a normalised fact whose `key` falls outside the
+  repo root or names another consumer project.
+- Do NOT delete a stale curated entry without explicit user
+  confirmation. Stale-flag is the most this skill emits.
+
+## Runnable example
+
+After a 4-day refactor of `app/Services/PaymentGateway`, run a
+consolidation cycle:
+
+- `/memory:mine-session --since 2026-05-06 --confirm-transcript-access --preview`.
+- Miner surfaces 4 facts: 1 correction (`PaymentGateway::charge` must
+  not throw on idempotency replays — `convention`), 1 decision
+  (`Stripe webhook signing key lives in `config/services.php` only —
+  `gotcha`), 2 patterns (`PaymentGatewayTest` flakes when seeded data
+  carries timestamps in microseconds — `pattern + gotcha`).
+- Report cites 0 stale flags. Re-run with `--commit-intake` after
+  spot-checking the 4 facts.
+- Hand off to `/memory:promote` for the curated-YAML write.

package/.agent-src/skills/release-comms/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: release-comms
+description: "Use when turning a shipped changelog into a release narrative — value-not-feature framing, audience-segmented surfaces, one source of truth. Triggers on 'announce the release', 'write changelog post'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product, team]
+---
+
+# release-comms
+
+## When to use
+
+- Release shipping with user-facing change, team about to send feature-list email.
+- Changelog draft reads like commit log — engineering-honest, unparseable for user.
+- Multiple comms surfaces (in-app, email, social, docs) about to be written by different people from same release.
+
+Do NOT use for incident comms (see `incident-commander`),
+deprecation announcements needing legal sign-off, or pre-release
+discovery — this skill assumes change is **shipped**.
+
+## Cognition cluster
+
+- **Mental model 16 — Leading vs. lagging indicators.** Release note
+  is lagging artifact; leading version = in-app prompt that fired
+  before user found change-log. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 16.
+- **Value-not-feature heuristic.** Every paragraph passes *"so the
+  user can ___"* completion. Failing rows go back for re-write.
+
+## Procedure
+
+### Step 0: Ground the release
+
+1. Read merged PR list / changelog block / release branch diff. Release = **what**; comms = **so what**. Conflate the two → ship marketing.
+2. Read **product** and **team** slots of [context-spine](../../../docs/contracts/context-spine.md) (if consumer filled them) for bounded scope and cadence — surface choice depends on cadence (weekly: in-app + log; quarterly: email + post; major: all four).
+3. Identify **single dominant change** the release ships. Three "headliners" reads as three half-announcements.
+
+### Step 1: Audience-segment
+
+1. Three audiences max: **active user**, **at-risk / lapsed user**, **prospect**. More fragments message; fewer hides routing.
+2. Per audience, write one sentence: *"After this release, you can …"* completing with user-side verb, not product-side feature.
+3. If two audiences end up with same sentence, collapse — segmentation that does not change message = theatre.
+
+### Step 2: Map surfaces to audiences
+
+1. **Changelog** (always) — engineers + power users; truthful, dense, link-heavy. Source of truth — every other surface points back here.
+2. **In-app prompt** — active users; ≤ 1 sentence + 1 CTA; fires for users whose past behaviour predicts they'll touch the new path.
+3. **Email** — at-risk / lapsed; one headline value, one CTA, one paragraph of context. No feature lists.
+4. **Social / blog** — prospect; the **why**, not the **what** — frame against user job (cite [`customer-research`](../customer-research/SKILL.md) if switch-event surfaced).
+
+Cut surfaces aggressively. Weekly release does not need blog post.
+
+### Step 3: Draft each surface from the changelog
+
+1. Open changelog. Per surface, copy dominant change line, then **rewrite verb subject** from "we" to "you".
+2. Strip qualifiers ("now", "even better", "lightning-fast"). Noise, not signal.
+3. Run *"so the user can ___"* completion on every paragraph. Failing paragraphs cut, not edited.
+
+### Step 4: Truth-check
+
+1. Every claim links back to changelog row or doc URL. Unsourced claim → cut.
+2. No tense games — past for shipped, future for coming-soon (and only if date is committed). "Roadmap" lives outside this skill.
+3. Names match product surface. In-app says "Reports" and email says "Insights" → user fires lookup tax.
+
+### Step 5: Hand off
+
+1. Produce four artifacts (see `## Output`).
+2. Hand to whoever owns send. Do not embed scheduling or A/B test plans here — that is RevOps.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Change is **shipped** and needs to reach existing users.
+- Multiple comms surfaces written by different people from same source.
+- Team about to default to feature-list email.
+
+**WHEN NOT to use this**
+
+- Production incident comms → [`incident-commander`](../incident-commander/SKILL.md).
+- Pre-release discovery / validation → [`customer-research`](../customer-research/SKILL.md).
+- Funnel-stage diagnostics post-release → [`funnel-analysis`](../funnel-analysis/SKILL.md).
+- Ranking which release to comms next → [`rice-prioritization`](../rice-prioritization/SKILL.md).
+
+## When the agent should load this
+
+- "Write the release notes for sprint 47."
+- "We're shipping the new export — how do we announce it?"
+- "Draft the changelog email for last week's batch."
+- "What's the in-app prompt copy for the redesign?"
+- "Turn the merged PR list into something users can read."
+
+## Output
+
+1. **`release-narrative.md`** — single source of truth: dominant change, audiences (1–3), per-audience *"After this release, you can …"* sentence, links to source changelog rows.
+2. **`changelog-entry.md`** — engineer-honest, dense, link-heavy block ready to paste into project's changelog.
+3. **`comms-pack.md`** — per-surface drafts (in-app prompt, email, optional social/blog), each ≤ surface's hard cap, each pointing back to `changelog-entry.md`.
+4. **`comms-checklist.md`** — pre-send checks: every claim sourced, names consistent across surfaces, audience match, "so the user can …" completion passing on every paragraph. Hand-off artifact for senior PO ([`product-owner`](../../personas/product-owner.md)).
+
+## Gotcha
+
+- Default failure mode = feature-list email — written to make engineering feel seen, not to help user.
+- Marketing puffery ("revolutionary", "delightful") fails source check; cut on sight.
+- Two surfaces using different names for same thing = highest-frequency support-ticket trigger after release.
+- Hidden coming-soon claims in past-tense paragraphs erode trust faster than missing the comms entirely.
+
+## Do NOT
+
+- Do NOT promote coming-soon item alongside shipped items — user cannot tell which is which and stops trusting next note.
+- Do NOT let long-tail change steal the headline — dominant change earns headline, long tail goes in changelog.
+- Do NOT ship surfaces without truth-check pass; unsourced claim survives in social longer than release does.
+
+## Runnable example
+
+Sprint 47 ships a one-click monthly export and three small bug fixes:
+
+- Dominant change: one-click export. Bug fixes go in changelog only.
+- Audiences: active user (will use it), at-risk (export friction was churn trigger per [`customer-research`](../customer-research/SKILL.md) evidence-log).
+- "After this release, you can pull a board-ready monthly report in one click." (active, at-risk — same sentence ⇒ collapse to one).
+- Surfaces: changelog (full), in-app prompt to active users on next month-end, email to at-risk cohort with same sentence and one CTA. No social.
+- Truth-check: claim links to export PR; "one click" is literal — verified against shipped UI.

package/.agent-src/skills/roadmap-writing/SKILL.md

@@ -162,6 +162,6 @@ to every roadmap you author.
 
 ## Examples
 
-Browse `agents/roadmaps/` (active plate) and `agents/roadmaps/archive/`
+Browse `agents/roadmaps/` (active set) and `agents/roadmaps/archive/`
 (closed work) for canonical structural / tactical / structural-with-council
 examples.

package/.agent-src/skills/stakeholder-tradeoff/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: stakeholder-tradeoff
 description: "Use when stakeholders pull a decision in different directions — frames each lens, builds a trade-off matrix, surfaces the cost of every choice — even if the user just says 'PO and ops disagree'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [team, product]
 personas:
   - product-owner
   - stakeholder
   - critical-challenger
-source: package
-domain: product
 ---
 
 # stakeholder-tradeoff
@@ -38,6 +41,26 @@ Do NOT use when:
 - The trade-off is risk-only — route to
   [`risk-officer`](../risk-officer/SKILL.md).
 
+## Cognition cluster
+
+- **Mental model 5 — Opportunity cost.** Every `+` on the matrix is
+  also an opportunity cost on the stakeholders not getting that
+  benefit; the matrix only earns its keep when it surfaces who pays
+  for the chosen `+`. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 5.
+- **Mental model 27 — Outcome over output.** Picking the option with
+  the most checkmarks is output theatre; pick the option whose `–`
+  cells land on stakeholders who can execute mitigations. See
+  `mental-models.md` § 27.
+- **Mental model 29 — Pre-mortems.** For the recommended option,
+  state the failure mode each `–`-bearing stakeholder will name in
+  six months. If you cannot, the lens is incomplete — re-interview.
+  See `mental-models.md` § 29.
+- **Team + product context-spine slots.** Read **team** for the
+  silent-stakeholders inventory (on-call, support, finance) and
+  **product** for end-user / segment lenses (free vs paid, region,
+  cohort). See [`context-spine`](../../../docs/contracts/context-spine.md).
+
 ## Procedure
 
 ### 1. Identify the stakeholders
@@ -98,7 +121,40 @@ everywhere, the trade-off paragraph names a concrete cost (not just
 cells the named owner can execute. Ensure no silent stakeholder
 column is missing.
 
-## Output format
+## Related Skills
+
+**WHEN to use this**
+
+- A request crosses two stakeholder lenses (eng ↔ PO, PO ↔ ops, ops
+  ↔ infra) and the trade-off is **not yet code**.
+- The room agrees on the goal but disagrees on who absorbs the cost.
+- A roadmap step has *un*declared trade-offs that need surfacing
+  before commit.
+
+**WHEN NOT to use this**
+
+- The conflict surfaces **inside an open PR** (test-coverage fails
+  but PO wants to ship) — start with `code-review-multi-lens`
+  (sibling C8); a C8 verdict that surfaces stakeholder conflict
+  becomes input to this skill for escalation. Boundary prose lives
+  in [`docs/guidelines/cross-role-handoff.md`](../../../docs/guidelines/cross-role-handoff.md).
+- The trade-off is purely technical (perf vs storage, sync vs async)
+  — route to [`decision-record`](../decision-record/SKILL.md).
+- The dominant axis is risk, not stakeholder cost — route to
+  [`risk-officer`](../risk-officer/SKILL.md).
+- The output is the locked decision artifact — hand off to
+  [`decision-record`](../decision-record/SKILL.md) once the matrix
+  is built.
+
+## When the agent should load this
+
+- "Wer zahlt was bei dieser Entscheidung?"
+- "PO und Ops sind sich uneinig — wir brauchen Klarheit."
+- "Was ist der Trade-off zwischen X und Y für die einzelnen Lenses?"
+- "Stakeholder-Konflikt vor dem Commit auflösen."
+- "Diese Roadmap-Phase hat undeclared trade-offs."
+
+## Output
 
 The trade-off report is a single block with these ordered fields:
 
@@ -147,3 +203,35 @@ Next:           /decision-record  to lock the choice
   if it exists, the trade-off was imaginary; surface that.
 - Do NOT lock the choice in this skill; hand off to
   `decision-record`.
+
+## Runnable example
+
+A pricing-page rewrite that ships faster vs gives ops more lead time:
+
+- Decision: *"Should the pricing-page rewrite ship in 2 weeks
+  (option A) or 4 weeks with a managed rollout (option B)?"*
+- Stakeholders:
+  - **PO** wants: revenue lift on Q-end · fears: churn signal in
+    the noise · trades: copy polish for time-to-ship.
+  - **On-call eng** wants: change window outside Friday · fears:
+    Saturday paging on a marketing rollout · trades: shippable A/B
+    framework for a deploy gate.
+  - **Support lead** wants: scripted answers for the new tier ·
+    fears: ticket-volume spike unprepared · trades: depth of
+    answers for breadth.
+  - **End-user (free tier)** wants: clear "what stays free" line ·
+    fears: silent paywall on a feature they rely on · trades:
+    nothing — silent stakeholder.
+- Matrix splits hardest on **operational load** (option A: `–` for
+  on-call + support, `+` for PO) and **clarity for end-users**
+  (option B: `+` for support + end-user, `–` for PO timing).
+- Trade-off in plain language: *"Option A means PO hits Q-end, but
+  on-call carries a marketing-rollout pager and support eats ticket
+  spikes blind. Option B means support and end-users land softly,
+  but PO slips two weeks past Q-end."*
+- Recommendation: option B. Rationale: the `–` cells in option A
+  land on stakeholders who **cannot** mitigate from inside the
+  rollout (free-tier user has no voice in the room).
+- Next: `/decision-record` to lock option B; the supersession chain
+  cites the original "ship by Q-end" mandate as the constraint that
+  changed.

package/.agent-src/skills/voc-extract/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: voc-extract
+description: "Use when extracting Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns. Triggers on 'what are users saying', 'recurring complaints', 'top themes'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product]
+---
+
+# voc-extract
+
+## When to use
+
+- A backlog or planning round needs grounded user-voice signal, not anecdotes.
+- A round of bug reports / feature requests / Sentry events has accumulated and the team needs themes with citation per theme.
+- A roadmap proposal needs a "what users keep telling us" backing section.
+
+Do NOT use this skill for live interviews
+([`discovery-interview`](../discovery-interview/SKILL.md)) or for
+quantitative funnel diagnosis ([`funnel-analysis`](../funnel-analysis/SKILL.md)).
+
+## Bounded scope
+
+- **Read-only on artefacts the host already has** — local repo issues
+  (`gh issue list`), PR discussions (`gh pr view`), Sentry projects
+  the team owns. No external scrape, no SaaS API calls.
+- **Chat-export sourcing (Discord, Slack) is deferred** pending
+  privacy review (council Q5, SHIP-WITHOUT). If a request asks for
+  chat-derived VoC, refuse and route the user to a privacy review.
+- **No PII surfacing** — quotes are paraphrased to remove names,
+  emails, tenant identifiers; verbatim is reserved for product-team
+  artefacts inside the repo.
+
+## Cognition cluster
+
+- **Mental model 15 — Signal vs noise.** A loud single reporter
+  swamps quiet recurring patterns; rank by **distinct authors**, not
+  comment count. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 15.
+- **Mental model 14 — Pareto.** Roughly 20% of themes carry 80% of
+  the contact volume; cut the long tail explicitly so the team acts
+  on the head. See `mental-models.md` § 14.
+- **Mental model 22 — Data-informed, not data-driven.** Issue counts
+  are evidence, not voting; weight by recency, severity, and segment
+  before recommending. See `mental-models.md` § 22.
+- **Product context-spine slot.** Read **product** for segments,
+  non-goals, and focal jobs; do not surface themes that fall outside
+  the declared scope without a scope-violation flag. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### 1. Inventory the source artefacts
+
+Identify what is in scope **for this run**:
+
+- `gh issue list --state all --limit N` per repo.
+- `gh pr list --state all --limit N` per repo.
+- Sentry project names + date window.
+
+Capture counts and date window in the output header so the verdict
+is reproducible.
+
+### 2. Inspect each artefact and tag
+
+Per artefact, capture:
+
+- **Theme tag** (free-text, normalised in step 3).
+- **Author** (distinct identity).
+- **Severity** — blocking / friction / wish / praise.
+- **Segment** — derived from the **product** spine slot.
+- **Citation** — `repo#123`, PR URL, Sentry issue ID.
+
+### 3. Normalise and rank
+
+Cluster theme tags into 5–12 themes max. For each:
+
+- **Distinct-author count** (the rank key).
+- **Severity mix** (blocking-share matters more than wish-share).
+- **Recency** — last 90 days vs older; weight 2× recent.
+- **Segment skew** — does the theme cluster in one segment?
+
+Drop themes with `< 3` distinct authors **unless** severity is
+blocking or the theme is brand-new in the recency window.
+
+### 4. Build the theme report and validate
+
+One row per theme. Columns: **theme · distinct authors · severity
+mix · recency · segment skew · representative citations (≤ 3) ·
+proposed next step (refine / probe / defer)**.
+
+Validate the report before handing back: verify each row cites
+≥ 1 artefact, check that distinct-author counts match the source
+inventory from step 1, confirm no PII leaked into the citations,
+and ensure no theme rated `defer` lacks a written rationale.
+
+### 5. Surface scope violations
+
+Themes that fall outside the **product** spine slot's declared scope
+go into a `scope-violation.md` block, never silently into the main
+report. The team decides whether to expand scope or close the door.
+
+### 6. Hand back
+
+Route refine candidates to [`refine-ticket`](../refine-ticket/SKILL.md);
+route probe candidates (need live interview) to
+[`discovery-interview`](../discovery-interview/SKILL.md); defer the
+rest with explicit rationale.
+
+## Related Skills
+
+**WHEN to use this**
+
+- The signal needs to come from existing repo / Sentry artefacts.
+- The output is a theme list with citation, not narrative summary.
+- A roadmap proposal needs grounded VoC backing.
+
+**WHEN NOT to use this**
+
+- The signal needs a live conversation — route to
+  [`discovery-interview`](../discovery-interview/SKILL.md).
+- The artefacts are chat-export sourced (Discord, Slack) — refuse
+  and route to a privacy review (deferred per bounded scope).
+- The output is a quantitative funnel — route to
+  [`funnel-analysis`](../funnel-analysis/SKILL.md).
+- A theme is already a ticket candidate — route directly to
+  [`refine-ticket`](../refine-ticket/SKILL.md).
+
+## When the agent should load this
+
+- "Was sagen die User wirklich?"
+- "Top-Themen aus den letzten 90 Tagen Issues."
+- "Welche Sentry-Patterns sind recurring?"
+- "Backe der Roadmap-Phase ein VoC-Block dazu."
+- "Gibt es ein Segment, das uns überproportional pingt?"
+
+## Output
+
+1. **Header** — sources scanned, counts, date window, scope notes.
+2. **Theme report table** — themes, distinct authors, severity mix,
+   recency, segment skew, citations, next step.
+3. **Scope-violation block** — themes outside the product spine
+   slot, explicit, never collapsed into the main table.
+4. **Routing list** — refine / probe / defer rows with the named
+   downstream skill per theme.
+
+## Gotcha
+
+- One articulate user can own three themes; rank by distinct authors
+  or you ship their backlog.
+- A theme with no recency (all > 90 days) is archaeology, not VoC;
+  flag it explicitly.
+- Chat-export requests are tempting (Discord copy-paste); refuse
+  per bounded scope until the privacy review lands.
+
+## Do NOT
+
+- Do NOT scrape external sources or hit SaaS APIs the team does not
+  already own.
+- Do NOT surface PII; paraphrase before quoting.
+- Do NOT collapse scope-violations into the main table.
+- Do NOT lock decisions inside this skill — hand off to
+  `refine-ticket` or `decision-record`.

package/.agent-src/templates/roadmaps.md

@@ -43,6 +43,20 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
     or budget-invariant changes; multi-round council, file-ownership
     matrices, > 600 lines. Enforced by `task lint-roadmap-complexity`.
     Standard: [`docs/contracts/roadmap-complexity-standard.md`](../docs/contracts/roadmap-complexity-standard.md).
+16. **Time-boxed plates / visible-horizon sections — opt-in via
+    `roadmap.horizon_weeks` in `.agent-settings.yml`.** Default is `0`
+    (off): roadmaps describe scope and phase ordering, not week-by-week
+    commitments. With the default, do **not** add `## Horizon (N-week
+    visible plate)` sections, "Inside / outside the plate" framings,
+    `In-plate?` columns in decision tables, or `**Out-of-plate.**` /
+    `**Out-of-horizon.**` / `(out-of-horizon, gated on Phase N)`
+    suffixes on steps or phase headers. AI execution does not operate
+    on calendar plates by default; scope ordering and dependency gates
+    are sufficient. Pacing is the user's call, decided per turn —
+    never encoded into the plan unless they have explicitly set
+    `horizon_weeks` to a positive integer. Enforced by
+    `task lint-roadmap-complexity` (plate-token detection skipped when
+    `horizon_weeks > 0`).
 
 ---