@event4u/agent-config 6.0.0 → 7.0.0

package/CONTRIBUTING.md

@@ -79,7 +79,7 @@ Helper commands:
 task sync             # src/ → dist/agent-src/, then project → .augment/
 task generate-tools   # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
 task test             # pytest tests/ + installer integration tests
-task lint-skills      # python3 scripts/skill_linter.py --all
+task lint-skills      # ./scripts-run src/scripts/skill_linter --all
 ```
 
 ## Branches, commits, and PRs

package/README.md

@@ -1,6 +1,6 @@
 <p align="center"><a href="https://event4u.app"><img alt="event4u Agent Config" src=".github/assets/banner.png"></a></p>
 
-# Agent Config — Universal AI Agent OS
+# Agent Config — Governed skills, rules & work journeys for AI coding agents
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
 
@@ -8,6 +8,16 @@
 
 Six role-shaped entry paths, one shared **skills + rules + commands** layer that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member — without locking you to a single model or vendor.
 
+### What's different
+
+Three things this package ships that a README scan slides right past:
+
+- **Surgical uninstall** — removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries.
+- **Pack-scoped install** — writes the active pack only, not a 500-artefact dump.
+- **Portability guard** — works in any project; source confidentiality is CI-enforced.
+
+See exactly [what works on which host](docs/capability-matrix.md), or jump to [things you can do in a minute](docs/cookbook.md).
+
 ### Pick your profile — six entry paths
 
 `agent-config setup` writes `profile.id` to `.agent-settings.yml`; each
@@ -66,7 +76,7 @@ is platform operation, not a user-work flow.)
 </p>
 
 <p align="center">
-  <sub>Distribution: <code>npm install @event4u/agent-config</code> · npm-primary per <a href="docs/decisions/ADR-033-distribution-identity-npm-primary.md">ADR-033</a>. Major bumps follow <a href="CONTRIBUTING.md#versioning-policy">semver</a>; each ships a <a href="CHANGELOG.md#breaking--v400-unified-setup-road-to-unified-setup"><code>### Breaking</code></a> entry — all majors indexed in <a href="BREAKING_CHANGES.md">BREAKING_CHANGES.md</a>.</sub>
+  <sub>Distribution: <code>npm install @event4u/agent-config</code>. Major bumps follow <a href="CONTRIBUTING.md#versioning-policy">semver</a>; each ships a <a href="CHANGELOG.md#breaking--v400-unified-setup-road-to-unified-setup"><code>### Breaking</code></a> entry — all majors indexed in <a href="BREAKING_CHANGES.md">BREAKING_CHANGES.md</a>.</sub>
 </p>
 
 ---
@@ -76,7 +86,7 @@ is platform operation, not a user-work flow.)
 <details>
 <summary><b>Catalog at a glance</b> — raw artefact counts (maintainer reference)</summary>
 
-[![Skills](https://img.shields.io/badge/Skills-227-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-79-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-150-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-78-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-251-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-88-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-161-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-82-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-26-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 The headline is the **experience** (profile + packs), not the raw counts. Full catalog: [`docs/catalog.md`](docs/catalog.md).
 </details>
@@ -88,7 +98,7 @@ your stack, and you ship work end-to-end. New install? Start with the
 [Quickstart](#quickstart). Already installed? [Supported tools](#supported-tools)
 shows the wired AIs; [`docs/featured-commands.md`](docs/featured-commands.md)
 lists the end-to-end workflows (`/implement-ticket`, `/work`,
-`/commit`, `/create-pr`). Deeper tour: [2-minute demo](#2-minute-demo--implement-ticket).
+`/commit`, `/pr:create`). Deeper tour: [2-minute demo](#2-minute-demo--implement-ticket).
 
 **Install scope.** Pick **one** scope per machine — project-local (default, recommended for application repos) or user-global (recommended for tooling repos / dotfiles). The installer refuses a second, conflicting scope via the `scope_guard` pre-flight. Details: [`docs/contracts/install-scopes.md`](docs/contracts/install-scopes.md). Cleanup when needed: `bash scripts/cleanup_other_scope.sh --confirm`.
 
@@ -108,6 +118,8 @@ Working on the package itself? [Development](#development) covers the
 opt-in measurement loop. Source-of-truth tree is
 `src/` (`src/skills`, `src/rules`, `src/agent-src/`); never hand-edit `.augment/` or `dist/agent-src/`.
 
+**Security.** Disclosure policy: [`SECURITY.md`](SECURITY.md). Threat model: [`docs/threat-model.md`](docs/threat-model.md).
+
 ---
 
 ## Quickstart
@@ -198,7 +210,7 @@ refine → memory → analyze → plan → implement → test → verify → rep
 - **Implements** under `minimal-safe-diff` + `scope-control` — no drive-by edits.
 - **Tests** (targeted first, full suite on success).
 - **Reviews** the diff through four judges (bugs, security, tests, code quality).
-- **Reports** changes, verdicts, follow-ups — then stops. `/commit` and `/create-pr` are suggestions, never auto-run.
+- **Reports** changes, verdicts, follow-ups — then stops. `/commit` and `/pr:create` are suggestions, never auto-run.
 
 Any ambiguity halts the flow with numbered options — never a silent guess. Persona comes from `.agent-settings.yml` (`roles.active_role`): `senior-engineer` (default), `qa`, or `advisory` (plan-only).
 
@@ -288,16 +300,6 @@ The Hard Floor on organization-mode features (SSO, central policy, OAuth connect
 
 > *The 9.3/10 feedback round (2026-05-25) re-asked for OAuth knowledge connectors, IAM / org governance, and organization-shared memory. Each is a stable cancellation row in [`team-deployment-posture`](docs/deploy/team-deployment-posture.md) under the same three release gates — recruited team customer · funded audit · maintainer ADR.*
 
-### Optional: persistent agent memory
-
-[`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory) — MCP-based backend for cross-session learnings. **Strictly optional**; without it, skills fall back to file-based memory under `agents/memory/`.
-
-```bash
-npm install --save-dev @event4u/agent-memory
-```
-
-→ [Memory contract](docs/contracts/agent-memory-contract.md) · [Built-in MCP server](docs/mcp-server.md) (experimental)
-
 ---
 
 ## Harness expectations
@@ -405,7 +407,7 @@ When a prompt matches a command's purpose ("setze ticket ABC-123 um" → `/imple
 | [**Migration**](docs/MIGRATION.md) | Per-version upgrade steps |
 | [**Showcase**](docs/showcase.md) | More examples & expected behavior |
 
-Browse content: [all 150 commands](dist/agent-src/commands/) · [skills catalog](docs/skills-catalog.md) · [full catalog](docs/catalog.md) · [`llms.txt`](llms.txt).
+Browse content: [all 161 commands](dist/agent-src/commands/) · [skills catalog](docs/skills-catalog.md) · [full catalog](docs/catalog.md) · [`llms.txt`](llms.txt).
 
 ---
 

package/dist/agent-src/commands/agent-handoff.md

@@ -6,6 +6,7 @@ intent: "Generate a session-handoff summary to continue work in a fresh chat"
 routes_to: [agent-docs-writing]
 replaces: []
 tier: 0
+visibility: visible
 skills: [agent-docs-writing]
 description: Generate a context summary for continuing work in a fresh chat. Replaces the session system.
 suggestion:
@@ -114,10 +115,10 @@ do not auto-execute.
   fingerprint derived from the platform `session_id` (schema v4, see
   [`chat-history-platform-hooks`](../../agents/settings/contexts/chat-history-platform-hooks.md)).
   Works only on the same machine and same repo, but captures every
-  phase / decision any session logged. Inspect with `/chat-history show`;
-  pull prior-session context into the current chat verbatim with
-  `/chat-history import`; mine a prior session for project-improving
-  learnings with `/chat-history learn`.
+  phase / decision any session logged. Pull prior-session context into
+  the current chat verbatim with `/chat-history import`; mine a prior
+  session for project-improving learnings with
+  `/memory mine-session --mode=proposals`.
 
 Prefer `/agent-handoff` for planned context switches across tools or
 machines; use `/chat-history import` after a crash or fresh-chat reopen

package/dist/agent-src/commands/agent-status.md

@@ -6,6 +6,7 @@ intent: "Report the current agent session state, mode, and progress at a glance"
 routes_to: [agent-docs-writing]
 replaces: []
 tier: 0
+visibility: visible
 skills: [agent-docs-writing]
 description: Show current conversation stats — message count, token costs, task progress, next freshness check.
 suggestion:
@@ -69,10 +70,10 @@ implementation: [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs).
 
 Run two read-only Python helpers (stdlib-only, no-op safe if JSONL missing):
 
-- `python3 scripts/telegraph_stats.py --format json` — per-session +
+- `./scripts-run src/scripts/telegraph_stats --format json` — per-session +
   per-conversation + lifetime telegraph delta. Honors suspended
   multiplier (see [`docs/contracts/telegraph-telemetry.md`](../docs/contracts/telegraph-telemetry.md)) — delta reads `0` while suspended; display version + ACTIVE/SUSPENDED state regardless.
-- `python3 scripts/cost_by_conversation.py --format json` — per-conversation
+- `./scripts-run src/scripts/cost_by_conversation --format json` — per-conversation
   total cost + model breakdown for current conversation, sourced
   from same `agents/cost-tracking/sessions.jsonl` ledger.
 

package/dist/agent-src/commands/agents/audit.md

@@ -3,6 +3,7 @@ model_tier: medium
 name: agents-audit
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: audit
 description: Audit agent infrastructure — token overhead, rule triggers, AGENTS.md health, Capability-over-Structure adherence, stale references. Read-only, suggest-only, never auto-apply.
@@ -88,7 +89,7 @@ Surface candidates with explicit justification. Never auto-apply.
 Run the linter and inspect output:
 
 ```bash
-python3 scripts/lint_agents_md.py
+./scripts-run src/scripts/lint_agents_md
 wc -c AGENTS.md
 ```
 
@@ -104,7 +105,7 @@ Failures route to `/agents optimize` — this command does **not** edit.
 ### 5. Check docs sync + stale references
 
 ```bash
-python3 scripts/check_references.py
+./scripts-run src/scripts/check_references
 ```
 
 Confirm counts/lists in `.augment/contexts/augment-infrastructure.md` and
@@ -113,7 +114,7 @@ Confirm counts/lists in `.augment/contexts/augment-infrastructure.md` and
 ### 6. Run skill linter
 
 ```bash
-python3 scripts/skill_linter.py --all --pairs --duplicates 2>&1 | grep "Summary:"
+./scripts-run src/scripts/skill_linter --all --pairs --duplicates 2>&1 | grep "Summary:"
 ```
 
 Report FAIL/WARN counts. Don't fix here — delegate to `skill-reviewer` or

package/dist/agent-src/commands/agents/init.md

@@ -3,6 +3,7 @@ model_tier: medium
 name: agents-init
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: init
 description: Initialize the agent layer for a consumer project — creates AGENTS.md and .github/copilot-instructions.md from package templates, auto-detects stack, never leaks other projects' identifiers.
@@ -156,7 +157,7 @@ module-aware skills (road-to-configurable-modules Phase B). Skips
 silently when the helper finds no candidates.
 
 ```bash
-python3 scripts/propose_modules_config.py --json
+./scripts-run src/scripts/propose_modules_config --json
 ```
 
 If the JSON `candidates` array is non-empty, render the proposed
@@ -177,6 +178,8 @@ contract). On skip, do nothing — the block stays opt-in.
 
 If `agents/` directory does not exist, suggest running `/optimize agents-dir --scaffold`.
 If `.agent-settings.yml` does not exist, suggest running `scripts/install` (then `/onboard` for first-run setup).
+If module candidates surfaced in Step 7 but the user skipped, note that
+`python3 scripts/propose_modules_config.py` can be re-run anytime.
 
 ## Rules
 

package/dist/agent-src/commands/agents/optimize.md

@@ -3,6 +3,7 @@ model_tier: inherit
 name: agents-optimize
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: optimize
 description: Refactor AGENTS.md to the Thin-Root contract (caps, pointer ratio, capability bullets, emergency-triage) and propagate to tool stubs. Suggest only, never auto-apply.
@@ -62,8 +63,8 @@ ask:
 ```bash
 target="<path-to-AGENTS.md>"
 wc -c "$target"
-python3 scripts/lint_agents_md.py 2>&1 | grep -A1 "$target" || \
-  python3 scripts/lint_agents_md.py
+./scripts-run src/scripts/lint_agents_md 2>&1 | grep -A1 "$target" || \
+  ./scripts-run src/scripts/lint_agents_md
 ```
 
 Record: total chars, gap to FAIL/WARN cap, pointer-ratio output,
@@ -150,8 +151,8 @@ as a finding in the step-7 numbered options instead of editing here.
 ### 9. Verify before claiming done
 
 ```bash
-python3 scripts/lint_agents_md.py
-python3 scripts/check_references.py
+./scripts-run src/scripts/lint_agents_md
+./scripts-run src/scripts/check_references
 ```
 
 Both green = the refactor is finished. Surface fresh output in the

package/dist/agent-src/commands/agents/user/accept.md

@@ -3,6 +3,7 @@ model_tier: medium
 name: agents-user-accept
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: user
 skills: [agents]

package/dist/agent-src/commands/agents/user/init.md

@@ -3,6 +3,7 @@ model_tier: medium
 name: agents-user-init
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: user
 skills: [agents]

package/dist/agent-src/commands/agents/user/review.md

@@ -3,6 +3,7 @@ model_tier: high
 name: agents-user-review
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: user
 skills: [agents]

package/dist/agent-src/commands/agents/user/show.md

@@ -3,6 +3,7 @@ model_tier: medium
 name: agents-user-show
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: user
 skills: [agents]

package/dist/agent-src/commands/agents/user/update.md

@@ -3,6 +3,7 @@ model_tier: medium
 name: agents-user-update
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: user
 description: Open .agent-user.md in the user's IDE for manual edit; validates schema and 100-line cap on save.

package/dist/agent-src/commands/agents/user.md

@@ -3,6 +3,7 @@ model_tier: medium
 name: agents-user
 pack: meta
 tier: 2
+visibility: internal
 cluster: agents
 sub: user
 description: User-persona file (.agent-user.md) — interview, render, and maintain who the user is and how they want to be addressed.

package/dist/agent-src/commands/agents.md

@@ -7,6 +7,7 @@ intent: "Manage the AGENTS.md file family — init, optimize, audit, user person
 routes_to: [agents-init, agents-optimize, agents-audit, agents-user]
 replaces: []
 tier: 1
+visibility: advanced
 description: Agent-layer orchestrator — routes to init, optimize, audit. Covers AGENTS.md and its multi-tool stubs (CLAUDE.md, GEMINI.md, copilot-instructions.md, .cursorrules).
 cluster: agents
 type: orchestrator

package/dist/agent-src/commands/analytics/prune.md

@@ -1,8 +1,9 @@
 ---
 model_tier: medium
 name: analytics-prune
-pack: meta
+pack: analytics
 tier: 2
+visibility: internal
 cluster: analytics
 sub: prune
 description: Drop events older than the 90-day retention window from the local analytics log. Atomic and idempotent.
@@ -14,7 +15,7 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - meta
+  - analytics
 ---
 
 # /analytics prune

package/dist/agent-src/commands/analytics/show.md

@@ -1,8 +1,9 @@
 ---
 model_tier: medium
 name: analytics-show
-pack: meta
+pack: analytics
 tier: 2
+visibility: internal
 cluster: analytics
 sub: show
 description: Render top prompts, launcher → completion rate per role, average session length, and knowledge-source usage from the local analytics log.
@@ -14,7 +15,7 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - meta
+  - analytics
 ---
 
 # /analytics show

package/dist/agent-src/commands/analytics.md

@@ -1,8 +1,9 @@
 ---
 model_tier: medium
 name: analytics
-pack: meta
+pack: analytics
 tier: 2
+visibility: internal
 description: Analytics orchestrator — routes to show, prune. Local-only workspace event log under `~/.event4u/agent-config/workspace/analytics/`.
 cluster: analytics
 type: orchestrator
@@ -14,7 +15,7 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - meta
+  - analytics
 ---
 
 # /analytics

package/dist/agent-src/commands/analyze/decision.md

@@ -0,0 +1,108 @@
+---
+model_tier: inherit
+name: analyze-decision
+pack: analysis-workbench
+tier: 2
+visibility: internal
+cluster: analyze
+sub: decision
+skills: [decision-review]
+description: Audit a past architectural decision — restate what was chosen and why, compare original assumptions against reality now, produce a verdict (still valid / needs amendment / superseded).
+suggestion:
+  eligible: true
+  trigger_description: "decision review, ADR review, did this hold up, rückblick Architektur, past decision"
+  trigger_context: "user wants to audit a past architectural decision or ADR for continued validity"
+workspaces:
+  - engineering
+packs:
+  - analysis-workbench
+---
+
+# /analyze:decision
+
+Past-decision audit sub-command in the `/analyze` cluster.
+Loads and runs the
+[`decision-review`](../../../../skills/decision-review/SKILL.md) skill.
+
+## Instructions
+
+### 1. Identify the decision
+
+Ask the user (in their language) for:
+
+- The ADR identifier (e.g. `ADR-042`) or informal name.
+- The path to the ADR file, or the slug to look up in `docs/decisions/`
+  or `docs/adrs/`.
+
+If the user names the decision informally, check the index before
+reading the full file.
+
+### 2. Run the decision-review skill
+
+Delegate to
+[`decision-review`](../../../../skills/decision-review/SKILL.md) verbatim:
+
+1. **Locate and read the full ADR** before proceeding.
+2. **Restate** — chosen option, context then, assumptions, alternatives
+   rejected.
+3. **Compare to reality now** — for each assumption: held / broke /
+   unknown, with evidence. List new information not available at
+   decision time.
+4. **Verdict** — one of three:
+   - *Still valid* — document the validation date.
+   - *Needs amendment* — core decision stands; recommend specific
+     amendment.
+   - *Superseded* — name the successor option; recommend
+     `decision-record` + `adr-create` as the forward path.
+
+Hindsight discipline: judge each assumption against the information
+available at the time it was made, not against the outcome alone.
+
+### 3. Memory write-back (dedup-first)
+
+Before drafting a new candidate, call `retrieve()` over the same
+key-space (decision area, affected paths) per
+[`analysis-memory-loop.md § 2`](../../../../docs/contracts/analysis-memory-loop.md):
+
+- **Match found** → propose a `frequency` / `supersedes` update.
+- **No match** → draft a new `historical-patterns` candidate:
+
+```jsonc
+{
+  "type":              "historical-patterns",
+  "summary":           "<one-line pattern: what held or broke>",
+  "evidence_paths":    ["docs/decisions/ADR-NNN-<slug>.md"],
+  "decision_surface":  ["<area1>", "<area2>"],
+  "last_validated":    "<today-YYYY-MM-DD>",
+  "review_after_days": 90,
+  "applicable_scope":  "project"
+}
+```
+
+Surface the candidate and ask:
+
+> 1. Propose this candidate to `/memory propose` (recommended)
+> 2. Refine before proposing — suggest changes
+> 3. Skip memory candidate for now
+
+**Empfehlung:** 1
+
+If the candidate fails the admission gate (< 2 distinct evidence paths
+AND < 3 future decisions in `decision_surface`), surface the gap and
+suggest deferring or strengthening evidence before proposing.
+
+### Rules
+
+- Do NOT commit, push, or open a PR.
+- Do NOT auto-promote — `/memory propose` is the intake.
+- Do NOT re-litigate a decision confirmed still valid — acknowledge it,
+  note the validation date, stop.
+- Do NOT issue a "superseded" verdict without naming the successor
+  option and recommending the forward path to `decision-record` +
+  `adr-create`.
+
+## See also
+
+- [`decision-review`](../../../../skills/decision-review/SKILL.md)
+- [`analysis-memory-loop.md`](../../../../docs/contracts/analysis-memory-loop.md)
+- [`/analyze`](../command.md) — cluster orchestrator

package/dist/agent-src/commands/analyze/incident.md

@@ -0,0 +1,120 @@
+---
+model_tier: inherit
+name: analyze-incident
+pack: analysis-workbench
+tier: 2
+visibility: internal
+cluster: analyze
+sub: incident
+skills: [incident-commander, root-cause-frameworks, blameless-post-mortem]
+description: Full incident flow — incident-commander coordination, then RCA via root-cause-frameworks, then a blame-free write-up via blameless-post-mortem, ending with an incident-learnings candidate.
+suggestion:
+  eligible: true
+  trigger_description: "production is down, active incident, Vorfall, Prod ist down, full incident analysis"
+  trigger_context: "user is managing or reviewing a production incident end-to-end"
+workspaces:
+  - engineering
+packs:
+  - analysis-workbench
+---
+
+# /analyze:incident
+
+Full incident sub-command in the `/analyze` cluster.
+Chains three skills:
+
+1. [`incident-commander`](../../../../skills/incident-commander/SKILL.md) — live coordination.
+2. [`root-cause-frameworks`](../../../../skills/root-cause-frameworks/SKILL.md) — RCA after mitigation.
+3. [`blameless-post-mortem`](../../../../skills/blameless-post-mortem/SKILL.md) — write-up + memory candidate.
+
+## Instructions
+
+### Phase 1 — Live incident coordination
+
+Load
+[`incident-commander`](../../../../skills/incident-commander/SKILL.md)
+and follow its procedure verbatim:
+
+- Open an incident log, assign roles, establish communication cadence.
+- Drive mitigation loop until impact is contained.
+- Capture a timeline as the incident progresses.
+- Write a partial post-mortem skeleton when mitigation is confirmed
+  (title, severity, timeline, impact — root cause can be TBD).
+
+**Handoff trigger:** mitigation confirmed → proceed to Phase 2.
+Per
+[`analysis-memory-loop.md § 5`](../../../../docs/contracts/analysis-memory-loop.md),
+the skeleton is acceptable input with open root-cause items.
+
+### Phase 2 — Root-cause analysis
+
+Load
+[`root-cause-frameworks`](../../../../skills/root-cause-frameworks/SKILL.md)
+and run the appropriate framework (5-whys, fishbone, fault-tree, or
+STAMP/STPA) against the captured timeline:
+
+- Return ranked root-cause candidates with confidence levels.
+- Present candidates to the user — not a forced verdict.
+- If root cause remains unresolved, mark the skeleton `status: draft`.
+  Do not block on an unresolved RCA.
+
+### Phase 3 — Post-mortem write-up + memory candidate
+
+Load
+[`blameless-post-mortem`](../../../../skills/blameless-post-mortem/SKILL.md)
+and produce the full write-up:
+
+1. **Summary** — what failed, impact, duration.
+2. **Timeline** — chronological bullets from Phase 1.
+3. **Root cause** — confirmed or `status: draft`.
+4. **Contributing factors** — systemic, not individual.
+5. **Corrective actions** — numbered, owned, time-boxed.
+6. **What went well** — working safeguards.
+
+#### Memory write-back
+
+Dedup pre-check: call `retrieve()` over the same key-space (incident
+type, affected paths) per
+[`analysis-memory-loop.md § 2`](../../../../docs/contracts/analysis-memory-loop.md):
+
+- **Match found** → propose a `frequency` / `supersedes` update.
+- **No match** → draft a new `incident-learnings` candidate:
+
+```jsonc
+{
+  "type":              "incident-learnings",
+  "summary":           "<one-line pattern learned>",
+  "evidence_paths":    ["<path/to/post-mortem>", "<path/to/timeline>"],
+  "decision_surface":  ["<area1>", "<area2>"],
+  "last_validated":    "<today-YYYY-MM-DD>",
+  "review_after_days": 90,
+  "applicable_scope":  "project"
+}
+```
+
+Surface the draft and ask:
+
+> 1. Propose this candidate to `/memory propose` (recommended)
+> 2. Refine before proposing — suggest changes
+> 3. Skip memory candidate for now
+
+**Empfehlung:** 1
+
+### Rules
+
+- Do NOT commit, push, or open a PR.
+- Do NOT auto-promote — `/memory propose` is the intake.
+- Do NOT block on incomplete root cause — the skeleton from Phase 1 is
+  sufficient to enter Phase 3; mark `status: draft` if unresolved.
+- Systems and processes only — never name individuals.
+- Do NOT chain back to `/analyze:postmortem` — this command IS the
+  full incident flow end-to-end.
+
+## See also
+
+- [`incident-commander`](../../../../skills/incident-commander/SKILL.md)
+- [`root-cause-frameworks`](../../../../skills/root-cause-frameworks/SKILL.md)
+- [`blameless-post-mortem`](../../../../skills/blameless-post-mortem/SKILL.md)
+- [`analysis-memory-loop.md`](../../../../docs/contracts/analysis-memory-loop.md)
+- [`/analyze:postmortem`](../postmortem/command.md) — post-incident write-up only (no live coordination)
+- [`/analyze`](../command.md) — cluster orchestrator