code-ai-installer 2.1.0 → 2.3.0

package/domains/analytics/locales/en/.agents/workflows/analytics-pipeline-rules.md

@@ -0,0 +1,288 @@
+---
+name: analytics-pipeline-rules
+description: Absolute rules of the analytical pipeline — gates, discipline, inter-session protocol
+---
+
+# Analytical Pipeline Rules
+
+> [!CAUTION]
+> **🔴 ABSOLUTE RULE #1:** Skipping the pipeline is prohibited. No exceptions.
+> Every gate → read the agent → deliverable → `$gates` PASS → `$handoff` → **User sign-off** → next gate.
+
+---
+
+## Three Pipeline Modes
+
+### 🔵 Full Pipeline (`/analyze`) — 5 sessions
+Full analytical cycle with two competing teams, mediation, and a PDF report.
+
+```
+Session 1: CONDUCTOR → INTERVIEWER
+Session 2: CONDUCTOR → ANALYSTS (RESEARCHER → DATA_ANALYST → STRATEGIST)
+Session 3: CONDUCTOR → CRITICS   (RESEARCHER → DATA_ANALYST → STRATEGIST)
+Session 4: CONDUCTOR → MEDIATOR
+Session 5: CONDUCTOR → DESIGNER → LAYOUTER → RELEASE GATE
+```
+
+### 🟢 Quick Pipeline (`/quick-insight`) — 1 session
+A single team, no critics. Used for simple questions when adversarial analysis is excessive.
+
+```
+CONDUCTOR → INTERVIEWER → RESEARCHER → DATA_ANALYST → STRATEGIST → MEDIATOR → DESIGNER → LAYOUTER → RELEASE GATE
+```
+
+---
+
+## Decision Tree — mode selection
+
+```
+User request
+       │
+       ├── Complex strategic question? High stakes? Devil's advocate needed?
+       │   └── YES → /analyze (Full Pipeline, 5 sessions)
+       │
+       ├── Simple analytical question? Single framework? Quick check?
+       │   └── YES → /quick-insight (Quick Pipeline, 1 session)
+       │
+       ├── User explicitly specified a mode?
+       │   └── Use the specified mode
+       │
+       └── In doubt?
+           └── /analyze (better to play it safe)
+```
+
+---
+
+## Mandatory Discipline (MANDATORY ENFORCEMENT)
+
+### Rule 1: Gates cannot be skipped
+- The order of gates is defined by the mode's workflow.
+- Every gate requires: deliverable + `$gates` PASS + `$handoff` + user sign-off.
+- Skipping a gate → 🔴 **P0 / BLOCKER**.
+
+**Applied skills:** `$gates` (readiness check), `$board` (status tracking), `$handoff` (context transfer).
+
+### Rule 2: User sign-off at every gate
+- Transitioning to the next gate is **only** allowed after an explicit "Approved" from the user.
+- Upon sign-off, the user **verifies** that the AI correctly loaded the agent and its skills.
+- `ShouldAutoProceed = false` ALWAYS.
+
+**Applied skills:** `$gates` (requests Approved), `$handoff` (waits for Approved before transfer).
+
+### Rule 3: Agent protocol — step-by-step
+- Every § (paragraph) in `agents/<role>.md` is a separate action.
+- You cannot "collapse" multiple steps into one.
+- Before writing a deliverable — complete ALL steps of the protocol.
+
+### Rule 4: Web search is mandatory
+- The Researcher **must** use `$web-research` upon every launch.
+- The user's data is **mandatory** to be verified via external sources.
+- Without a web search, the deliverable is considered **INCOMPLETE**.
+
+**Applied skill:** `$web-research` (search protocol), `$gates` (RES-xx without web-research = automatic Blocker).
+
+### Rule 5: Team Mode is strictly defined
+- Conductor defines the team mode (Alpha/Beta) in the Handoff Envelope.
+- Researcher, Analyst, and Strategist must follow the assigned mode.
+- Critics (Beta) **must** receive the full Analysts' (Alpha) report as input.
+
+**Applied skills:** `$handoff` (team mode in envelope), `$gates` (team mode check).
+
+### Rule 6: Inter-session protocol
+- In the Full Pipeline, every session ends by saving `docs/analytics/session-N-handoff.md`.
+- The handoff file contains the **full text of artifacts** (not links — the next session lacks context).
+- A ready-to-use prompt for the next session is generated (`$session-prompt-generator`).
+- Without a handoff file, the session is considered **INCOMPLETE**.
+
+**Applied skills:** `$handoff` (Session type, full text), `$session-prompt-generator` (prompt), `$board` (state saving).
+
+### Rule 7: Mediator — impartiality
+- The Mediator evaluates the quality of arguments and evidence base, **not text volume**.
+- Evaluation mode (scoring/qualitative/synthesis) is determined during the interview.
+- Synthesis (Appendix D) — only upon Mediator's proposal and user's approval.
+
+---
+
+## Mapping "Rule → Skill → Check"
+
+| Rule | Skills | What is checked | In case of violation |
+|------|--------|-----------------|----------------------|
+| 1. Gates cannot be skipped | `$gates`, `$board`, `$handoff` | Statuses on the board flow sequentially, no gaps | 🔴 P0 Blocker |
+| 2. User sign-off | `$gates`, `$handoff` | Explicit "Approved" before every transition | 🔴 P0 Blocker |
+| 3. Agent protocol | `$gates` (dependency check) | All steps of the agent's protocol are completed | 🔴 P0 Blocker |
+| 4. Web search is mandatory | `$web-research`, `$gates` (RES-xx) | WebSearch/WebFetch completed, audit trail filled | 🔴 P0 Blocker |
+| 5. Team mode | `$handoff`, `$gates` (team mode check) | Agent works in the assigned Alpha/Beta mode | 🟠 P1 Important |
+| 6. Inter-session protocol | `$handoff` (Session), `$session-prompt-generator` | File saved, prompt generated, artifacts in full text | 🔴 P0 Blocker |
+| 7. Impartiality of Mediator | `$gates` (MED-xx) | Scoring/qualitative by criteria, not by volume | 🟠 P1 Important |
+
+---
+
+## Mechanical Blocks (mandatory forced checks)
+
+| # | Block | When | What it checks | On failure |
+|---|-------|------|----------------|------------|
+| 1 | **Pre-flight check** | Before writing a deliverable | Quote the last user's "Approved" | Stop, request Approved |
+| 2 | **Skill read check** | Before applying a skill | Read SKILL.md via `view_file` | Read, then apply |
+| 3 | **Data verification check** | Every fact in the deliverable | Source URL + date + confidence (✅/⚠️/🔮) | Mark as 🔮 Assumed or remove |
+| 4 | **Handoff file check** | Before closing the session (Full) | `docs/analytics/session-N-handoff.md` saved, self-contained | Do not close session, save file |
+| 5 | **Team mode check** | Conductor at every handoff | Agent works in the assigned team mode | Return and reassign |
+
+---
+
+## Escalation Protocol
+
+### When user sign-off is missing
+1. Show the deliverable and request "Approved".
+2. If there is no answer — **wait**. Do not proceed to the next gate.
+3. Remind: "Waiting for 'Approved' to transition to [next gate]".
+4. **Never** auto-proceed. `ShouldAutoProceed = false` ALWAYS.
+
+### Upon repeated FAILs at `$gates`
+| Iteration | Action |
+|:---------:|--------|
+| 1st FAIL | Standard return: list of gaps → agent revises |
+| 2nd FAIL | Extended return + specific instructions "how to fix" |
+| 3+ FAIL | **Escalation to user** via `$gates` protocol (options: scope revision / return to previous gate / forced CONDITIONAL PASS) |
+
+> Detailed escalation protocol — in `$gates` → "Escalation protocol on repeated FAILs".
+
+### Upon detecting an issue at a subsequent gate (Reverse Handoff)
+1. The agent forms a Reverse Handoff detailing the issue via `$handoff`.
+2. Conductor routes the return to the correct gate.
+3. The board (`$board`) is updated: current gate → `[↩]`, return gate → `[→]`.
+4. After correction — repeated check via `$gates`.
+
+> Detailed reverse handoff protocol — in `$handoff` → "Reverse Handoff".
+
+---
+
+## Pipeline Health Metrics
+
+`$board` calculates and displays upon every update:
+
+| Metric | Formula | Healthy | Problematic |
+|--------|---------|:-------:|:-----------:|
+| Progress (%) | Completed / Total × 100 | Growing | Stagnating |
+| Avg. time/gate | Σ time / completed | ≤ 15 min | > 30 min |
+| Blockers (total) | No. of [!] of all time | 0-1 | ≥ 3 |
+| Returns (total) | No. of [↩] of all time | 0-1 | ≥ 3 |
+| FAIL rate | FAILs / gate checks × 100 | < 20% | > 40% |
+
+**At FAIL rate > 40%:** Conductor escalates to the user — the scope might be too broad or data is insufficient.
+
+> Detailed metrics — in `$board` → "Progress Metrics".
+
+---
+
+## Priority Format
+
+| Priority | Description | Action |
+|:--------:|-------------|--------|
+| 🔴 **P0 / BLOCKER** | Blocks progress / report publication | Immediately: fix or escalate |
+| 🟠 **P1 / IMPORTANT** | Important to fix before finalization | Before Release Gate |
+| 🟡 **P2 / NICE-TO-HAVE** | Can be included in the next iteration | Backlog |
+
+---
+
+## Pipeline Artifacts
+
+### Full Pipeline
+
+| Session | Artifact | Format | Who creates | Skill |
+|:-------:|----------|--------|-------------|-------|
+| 1 | Interview Brief | Markdown | Interviewer | — |
+| 1 | Session 1 Handoff | `docs/analytics/session-1-handoff.md` | Conductor | `$handoff`, `$session-prompt-generator` |
+| 2 | Alpha Research Package | Markdown (in handoff) | Researcher (Alpha) | `$web-research` |
+| 2 | Alpha Analytical Report | Markdown (in handoff) | Data Analyst (Alpha) | Framework skills |
+| 2 | Alpha Strategy | Markdown (in handoff) | Strategist (Alpha) | — |
+| 2 | Session 2 Handoff | `docs/analytics/session-2-handoff.md` | Conductor | `$handoff`, `$session-prompt-generator` |
+| 3 | Beta Research Package | Markdown | Researcher (Beta) | `$web-research` |
+| 3 | Beta Analytical Report | Markdown | Data Analyst (Beta) | Framework skills (counter) |
+| 3 | Beta Strategy + Critique | Markdown | Strategist (Beta) | — |
+| 3 | Session 3 Handoff | `docs/analytics/session-3-handoff.md` | Conductor | `$handoff`, `$session-prompt-generator` |
+| 4 | Mediated Conclusion | Markdown | Mediator | — |
+| 4 | Synthesis (optional) | Markdown | Mediator | — |
+| 4 | Session 4 Handoff | `docs/analytics/session-4-handoff.md` | Conductor | `$handoff`, `$session-prompt-generator` |
+| 5 | Report Design Spec | Markdown | Designer | `$report-design` |
+| 5 | Final HTML Report | HTML → PDF | Layouter | `$html-pdf-report` |
+
+### Quick Pipeline
+
+| Artifact | Format | Who creates | Skill |
+|----------|--------|-------------|-------|
+| Interview Brief | Markdown | Interviewer | — |
+| Research Package | Markdown | Researcher | `$web-research` |
+| Analytical Report | Markdown | Data Analyst | Framework skills |
+| Strategy | Markdown | Strategist | — |
+| Conclusion | Markdown | Mediator | — |
+| Report Design Spec | Markdown | Designer | `$report-design` |
+| Final HTML Report | HTML → PDF | Layouter | `$html-pdf-report` |
+
+---
+
+## Example — Full Pipeline mid-flight (session 2, blocker resolved)
+
+```
+Session 1 (completed):
+  COND-01 [✓] → Decision Tree → Full Pipeline
+  INT-01  [✓] → Brief: 12 questions, scoring mode, scope = EdTech corp. training RF
+  → session-1-handoff.md saved ✅
+
+Session 2 (in progress):
+  COND-02 [✓] → Context loaded from session-1-handoff.md
+  RES-01  [✓] → CONDITIONAL PASS (2 gaps: TAM 2 sources, IDC 14 mo)
+                 $web-research: 38 queries, 48 sources, Verified 62% 🟡
+                 $handoff: envelope with gaps transferred to AN-01
+  AN-01   [→] → In progress: TAM/SAM/SOM + Competitive Analysis + PEST
+                 $gates dependency check: RES-01 data quoted ✅
+  ST-01   [ ] → Waiting
+
+Metrics: Progress 33% (5/15) | Avg. time/gate: 9 min | Blockers: 0 | Returns: 0
+```
+
+**What happened:**
+1. COND-01: Decision Tree → Full Pipeline. User: "Approved" ✅
+2. INT-01: 12 questions, scoring mode. User: "Approved" ✅
+3. Session 1 Handoff: file saved, prompt generated. User: "Approved" ✅
+4. COND-02: context loaded, verified. User: "Approved" ✅
+5. RES-01: `$web-research` completed (38 queries). `$gates`: CONDITIONAL PASS (2 gaps). User: "Approved" (marking the gaps) ✅
+6. AN-01: in progress. `$gates` dependency check: RES-01 data engaged.
+
+**Blocker-scenario (example):**
+If RES-01 did not perform `$web-research`:
+- `$gates` → automatic 🔴 Blocker (Rule 4).
+- `$board` → RES-01 [!] Blocker.
+- Escalation: "⚠️ Researcher did not perform a web search. This is a mandatory requirement."
+- Return: RES-01 [↩] → perform `$web-research` → repeated `$gates` check.
+
+---
+
+## Pipeline Startup Checklist (for Conductor)
+
+Conductor performs upon initialization:
+
+- [ ] Mode determined by Decision Tree (Full / Quick)
+- [ ] Board created via `$board` with correct gate IDs
+- [ ] First gate is activated (COND-01 → [→])
+- [ ] User sign-off obtained on mode and scope
+- [ ] For a continuing session: handoff file loaded and verified (`$handoff` recovery protocol)
+
+## Session Closing Checklist (for Conductor)
+
+Conductor performs before completion:
+
+- [ ] All gates of the current session in [✓] or [⊘] (no [→] or [!])
+- [ ] `$board` is saved in the handoff file
+- [ ] All artifacts are included in **full text** in the handoff
+- [ ] `$session-prompt-generator` called, prompt generated
+- [ ] Handoff file saved: `docs/analytics/session-N-handoff.md`
+- [ ] File is self-contained (test: possible to start work without external context)
+- [ ] User sign-off obtained to close the session
+
+## Release Gate Checklist (for Conductor, session 5)
+
+- [ ] All gates of all sessions are in [✓] on the `$board`
+- [ ] PDF report generated and visually checked (`$html-pdf-report` testing protocol)
+- [ ] Data in the report is up to date as of publication date
+- [ ] User sign-off obtained
+- [ ] Final board + log shown to the user

package/domains/analytics/locales/en/.agents/workflows/analyze.md

@@ -0,0 +1,395 @@
+---
+name: analyze
+description: Full analytical pipeline — 5 sessions, adversarial approach, mediation, PDF report
+---
+
+# Workflow: /analyze — Full Analytical Pipeline (5 sessions)
+
+## Description
+Full analytical pipeline with an adversarial approach. Two competing teams (Analysts and Critics) independently research the question, the Mediator evaluates the results, and the design/layout team prepares a PDF report. Divided into 5 sessions to manage context window limits.
+
+> **Pipeline rules:** This workflow obeys `analytics-pipeline-rules.md` — 7 mandatory rules, mechanical blocks, health metrics, and the escalation protocol.
+
+## When to use
+
+| Criterion | /analyze (Full) | /quick-insight (Quick) |
+|-----------|:---------------:|:----------------------:|
+| Complexity of the question | High: strategic, multifactorial | Low: single framework, quick check |
+| Stakes | High: investments, market entry, M&A | Low: internal report, exploration |
+| Devil's advocate needed? | Yes — critique strengthens the outcome | No — one perspective is sufficient |
+| PDF report | Yes — for a presentation | No — markdown is sufficient |
+| Time budget | 5 sessions (total 2-4 hours) | 1 session (30-60 min) |
+| When in doubt | ✅ **Use /analyze** | |
+
+## When NOT to use
+- Simple analytical question → `/quick-insight`.
+- A fast answer needed without a PDF → `/quick-insight`.
+
+> Quick Pipeline is described in `quick-insight.md`. All gates covered in one session, without competing teams.
+
+## Workflow Inputs
+
+| Field | Required | Description |
+|-------|:--------:|-------------|
+| Question / topic | ✅ | What needs to be analyzed — from the user |
+| User data | ⬚ | Any available data, reports, metrics |
+| Industry / market | ⬚ | If known in advance. If not — Interviewer will clarify |
+| Budget / resources | ⬚ | Context for strategic recommendations |
+| Deadline | ⬚ | Influences the depth of research |
+
+---
+
+## Pipeline (5 sessions)
+
+```
+┌─────────── Session 1 ───────────┐
+│ COND-01 → INT-01                │ → session-1-handoff.md
+└─────────────────────────────────┘
+
+┌─────────── Session 2 ───────────┐
+│ COND-02 → RES-01(α)             │
+│         → AN-01(α)              │
+│         → ST-01(α)              │ → session-2-handoff.md
+└─────────────────────────────────┘
+
+┌─────────── Session 3 ───────────┐
+│ COND-03 → RES-02(β)             │
+│         → AN-02(β)              │
+│         → ST-02(β)              │ → session-3-handoff.md
+└─────────────────────────────────┘
+
+┌─────────── Session 4 ───────────┐
+│ COND-04 → MED-01                │ → session-4-handoff.md
+│ (opt: MED-01 Synthesis)         │
+└─────────────────────────────────┘
+
+┌─────────── Session 5 ───────────┐
+│ COND-05 → DS-01 → LY-01         │ → PDF report
+│         → RG-01                 │
+└─────────────────────────────────┘
+```
+
+### Parallelism
+
+| Sessions | Parallel? | Reason |
+|----------|:---------:|--------|
+| Sessions 1-5 | ❌ Strictly sequential | Each depends on the previous handoff |
+| Inside session: gates | ❌ Sequential | Researcher → Data Analyst → Strategist |
+| Session 5: DS-01 → LY-01 | ❌ Sequential | Layouter implements the design spec |
+
+---
+
+## Gates and deliverables per session
+
+### Session 1: Interview
+
+#### COND-01: Conductor
+**Input:** User request
+**Actions:**
+1. Determine the scope and complexity of the question.
+2. Confirm `/analyze` mode (or switch to `/quick-insight`).
+3. Initialize the board (`$board` — Full Pipeline, 15 gates).
+4. Formulate the task for the Interviewer.
+5. `$gates` → `$handoff` → Interviewer.
+**Required skills:** `$board`, `$gates`, `$handoff`
+**Deliverable:** Board + Handoff Envelope → Interviewer
+**→ Wait for "Approved"**
+
+#### INT-01: Interviewer
+**Input:** `$handoff` from COND-01
+**Actions:**
+1. Adaptive interview — ask questions until obtaining sufficient context.
+2. Determine: question, industry, data, goal, timeline, Mediator evaluation method.
+3. Form a Research Brief.
+4. `$gates` → `$handoff` → Conductor.
+**Required skills:** `$gates`, `$handoff`
+**Deliverable:** Research Brief (scope, constraints, key questions, data sources, evaluation method)
+**→ Wait for "Approved"**
+
+#### End of session 1
+Conductor:
+1. Saves `docs/analytics/session-1-handoff.md` (full text of the Research Brief).
+2. Generates a prompt for session 2 (`$session-prompt-generator`).
+3. Shows the prompt to the user.
+
+---
+
+### Session 2: Team Alpha (Analysts)
+
+#### COND-02: Conductor (initialization)
+**Input:** `docs/analytics/session-1-handoff.md` (user pastes the prompt)
+**Actions:**
+1. Parse the handoff file — contextual restoration.
+2. Verify integrity (`$handoff` → recovery protocol, if file is incomplete).
+3. Load the Research Brief.
+4. Announce: "Session 2 — Analysts Team (Alpha)".
+5. Set team mode: `Alpha`.
+6. `$gates` → `$handoff` → RES-01.
+**→ Wait for "Approved"**
+
+#### RES-01: Researcher (Alpha)
+**Input:** Research Brief + `team: Alpha`
+**Actions:**
+1. Fact-check and data collection covering the key questions of the Research Brief.
+2. **Mandatory** web search (`$web-research`) — verification + supplementation.
+3. Form the Research Package (facts + sources + Tier + confidence level).
+4. `$gates` → `$handoff` → AN-01.
+**Required skills:** `$web-research`, `$gates`, `$handoff`
+**Deliverable:** Alpha Research Package (data with URLs, dates, confidence levels ✅/⚠️/🔮)
+**→ Wait for "Approved"**
+
+#### AN-01: Data Analyst (Alpha)
+**Input:** Alpha Research Package + Research Brief
+**Actions:**
+1. Select relevant frameworks (minimum 2 from the available list).
+2. Apply frameworks to the collected data.
+3. Structure and identify patterns.
+4. `$gates` (dependency check: RES-01 data quoted) → `$handoff` → ST-01.
+**Required skills:** Selected frameworks (from the catalog: `$swot-analysis`, `$tam-sam-som`, `$competitive-analysis`, `$pest-analysis`, `$porters-five-forces`, `$bcg-matrix`, `$ansoff-matrix`, `$blue-ocean-strategy`, `$value-chain-analysis`, `$cohort-analysis`, `$rfm-analysis`, `$unit-economics`, `$trend-analysis`, `$customer-journey-mapping`, `$icp-buyer-persona`, `$jtbd-analysis`), `$gates`, `$handoff`
+**Deliverable:** Alpha Analytical Report (frameworks + patterns + insights)
+**→ Wait for "Approved"**
+
+#### ST-01: Strategist (Alpha)
+**Input:** Alpha Research Package + Alpha Analytical Report
+**Actions:**
+1. Synthesize data and analytics into a strategy.
+2. Formulate recommendations tied to the evidence.
+3. Assess risks + action plan.
+4. `$gates` (dependency check: evidence from AN-01 and RES-01) → `$handoff` → Conductor.
+**Required skills:** `$gates`, `$handoff`
+**Deliverable:** Alpha Strategy Report (executive summary + insights + strategy + risks + action plan + KPIs)
+**→ Wait for "Approved"**
+
+#### End of session 2
+Conductor:
+1. Saves `docs/analytics/session-2-handoff.md` (full text: Research Brief + Alpha Research Package + Alpha Analytical Report + Alpha Strategy).
+2. Generates a prompt for session 3 (`$session-prompt-generator`).
+
+---
+
+### Session 3: Team Beta (Critics)
+
+#### COND-03: Conductor (initialization)
+**Input:** `docs/analytics/session-2-handoff.md`
+**Actions:**
+1. Parse the handoff — load the Research Brief + the full Alpha report.
+2. Verify integrity.
+3. Announce: "Session 3 — Critics Team (Beta)".
+4. Set team mode: `Beta`.
+5. Pass Alpha's full output as mandatory input to Beta.
+6. `$gates` → `$handoff` → RES-02.
+**→ Wait for "Approved"**
+
+#### RES-02: Researcher (Beta)
+**Input:** Research Brief + Alpha full output + `team: Beta`
+**Actions:**
+1. Independent research on the same questions (using proper, different sources if required).
+2. **Mandatory** web search (`$web-research`) — looking for counter-evidence.
+3. Analyze Alpha: identify gaps, weak sources, missing data.
+4. `$gates` → `$handoff` → AN-02.
+**Required skills:** `$web-research`, `$gates`, `$handoff`
+**Deliverable:** Beta Research Package (independent findings + Alpha gaps + counter-evidence)
+**→ Wait for "Approved"**
+
+#### AN-02: Data Analyst (Beta)
+**Input:** Beta Research Package + Alpha Analytical Report
+**Actions:**
+1. Critique Alpha's analytical conclusions (methodologies, frameworks, interpretations).
+2. Apply frameworks missed by Alpha (counter-frameworks).
+3. Deliver alternative analytics from a different perspective.
+4. `$gates` (dependency check: RES-02 data + critique of Alpha AN-01) → `$handoff` → ST-02.
+**Required skills:** counter-frameworks from the catalog, `$gates`, `$handoff`
+**Deliverable:** Beta Analytical Report (critique of Alpha + alternative analysis)
+**→ Wait for "Approved"**
+
+#### ST-02: Strategist (Beta)
+**Input:** Beta Research + Beta Analysis + Alpha Strategy
+**Actions:**
+1. Critique Alpha's strategy point-by-point with evidence.
+2. Identify risks skipped by Alpha.
+3. Form an alternative strategy.
+4. `$gates` → `$handoff` → Conductor.
+**Required skills:** `$gates`, `$handoff`
+**Deliverable:** Beta Strategy Report (critique of Alpha + alternative strategy + risks + action plan)
+**→ Wait for "Approved"**
+
+#### End of session 3
+Conductor:
+1. Saves `docs/analytics/session-3-handoff.md` (Research Brief + Alpha full Report + Beta full Report).
+2. Generates a prompt for session 4.
+
+---
+
+### Session 4: Mediation
+
+#### COND-04: Conductor (initialization)
+**Input:** `docs/analytics/session-3-handoff.md`
+**Actions:**
+1. Parse the handoff — load Research Brief + Alpha + Beta reports.
+2. Verify integrity.
+3. Announce: "Session 4 — Mediation".
+4. Confirm the evaluation method (determined during the interview).
+5. `$gates` → `$handoff` → MED-01.
+**→ Wait for "Approved"**
+
+#### MED-01: Mediator
+**Input:** Research Brief + Alpha full report + Beta full report + evaluation method
+**Actions:**
+1. Comparative analysis of Alpha vs Beta.
+2. Apply the chosen evaluation method (scoring / qualitative / both).
+3. Formulate the final conclusion and recommendations.
+4. Propose synthesis (Appendix D) — the user decides.
+5. `$gates` → `$handoff` → Conductor.
+**Required skills:** `$gates`, `$handoff`
+**Deliverable:** Mediated Conclusion (comparative analysis + scoring + recommendation + action items)
+**→ Wait for "Approved"**
+
+#### MED-01 Synthesis (optional)
+If the user approved the synthesis:
+1. Integrate the best elements from both teams.
+2. Create a synthesized strategy (Appendix D).
+**Deliverable:** Synthesis Report
+**→ Wait for "Approved"**
+
+#### End of session 4
+Conductor:
+1. Saves `docs/analytics/session-4-handoff.md` (Research Brief + Mediated Conclusion + Synthesis if any).
+2. Generates a prompt for session 5.
+
+---
+
+### Session 5: Report
+
+#### COND-05: Conductor (initialization)
+**Input:** `docs/analytics/session-4-handoff.md`
+**Actions:**
+1. Parse the handoff — load all artifacts for the report.
+2. Verify integrity.
+3. Announce: "Session 5 — Report Preparation".
+4. `$gates` → `$handoff` → DS-01.
+**→ Wait for "Approved"**
+
+#### DS-01: Designer
+**Input:** Mediated Conclusion + Alpha Report + Beta Report + Research Brief
+**Actions:**
+1. Design the report structure (`$report-design`).
+2. Map visualizations for each data block (decision tree from `$report-design`).
+3. Set the color palette and internal hierarchy.
+4. Draft the executive summary.
+5. `$gates` → `$handoff` → LY-01.
+**Required skills:** `$report-design`, `$gates`, `$handoff`
+**Deliverable:** Report Design Spec (structure + visualization map + palette + executive summary draft)
+**→ Wait for "Approved"**
+
+#### LY-01: Layouter
+**Input:** Report Design Spec + all data for the report
+**Actions:**
+1. Generate an HTML file with inline CSS (`$html-pdf-report`).
+2. Embed Chart.js charts and Mermaid diagrams.
+3. Layout all sections + Appendices A, B, C, D.
+4. Follow the PDF testing protocol (8 checks from `$html-pdf-report`).
+5. `$gates` → `$handoff` → Conductor.
+**Required skills:** `$html-pdf-report`, `$gates`, `$handoff`
+**Deliverable:** Self-contained HTML file (→ Print-to-PDF)
+**→ Wait for "Approved"**
+
+#### RG-01: Release Gate
+**Input:** HTML report + all deliverables
+**Check (checklist from `analytics-pipeline-rules.md`):**
+- [ ] All gates of all sessions are in [✓] on `$board`
+- [ ] PDF report generated and visually verified
+- [ ] Data is up to date as of the publication date
+- [ ] PDF contains: Title Page, TOC, Executive Summary, Main Section, Appendix A-C (D optional)
+- [ ] All data is verified (source URLs present)
+- [ ] Executive summary reflects mediation
+- [ ] Visualizations correspond correctly (Chart.js animation: false, Mermaid rendered)
+
+**Decision:** GO ✅ / NO-GO ❌ / GO-with-conditions ⚠️
+**→ Wait for "Approved"**
+
+---
+
+## Reverse Handoff — return protocol
+
+### Common return reasons
+
+| From Gate | Reason | Return to | Skill |
+|-----------|--------|-----------|-------|
+| AN-01/02 | Insufficient data | RES-01/02 | `$handoff` (Reverse) |
+| ST-01/02 | Analytics do not cover the question | AN-01/02 | `$handoff` (Reverse) |
+| MED-01 | Data contradict each other without explanation | RES-01 or RES-02 | `$handoff` (Reverse) |
+| DS-01 | No visualizable data | MED-01 | `$handoff` (Reverse) |
+| LY-01 | Incomplete design spec | DS-01 | `$handoff` (Reverse) |
+
+### Protocol
+1. The agent forms a Reverse Handoff via `$handoff` (what to fix + what NOT to touch).
+2. Conductor routes the return to the correct gate.
+3. The `$board` is updated: current → `[↩]`, return → `[→]`.
+4. After correction — repeated `$gates` verification.
+5. If the return spans across sessions — Conductor shapes a new handoff file.
+
+> Detailed protocol — in `$handoff` → "Reverse Handoff".
+
+---
+
+## Example — pipeline mid-flight (end of session 2)
+
+```
+📊 Progress: 40% (6/15) | Session: 2/5 | Avg. time/gate: 10 min | Blockers: 0 | Returns: 0
+
+| # | ID | Gate | Session | Status | Deliverable |
+|---|----|------|:-------:|:------:|-------------|
+| 1 | COND-01 | Conductor | 1 | [✓] | Full Pipeline, scope: EdTech corp. training RF |
+| 2 | INT-01 | Interviewer | 1 | [✓] | Brief: 12 questions, scoring mode |
+| 3 | COND-02 | Conductor (s.2) | 2 | [✓] | Context loaded, team Alpha |
+| 4 | RES-01 | Researcher (α) | 2 | [✓] | 28 sources, Verified 62% 🟡 |
+| 5 | AN-01 | Data Analyst (α) | 2 | [✓] | TAM/SAM/SOM + Competitive + PEST |
+| 6 | ST-01 | Strategist (α) | 2 | [✓] | AI-first corp. learning, 5 recommendations |
+| 7 | COND-03 | Conductor (s.3) | 3 | [ ] | — |
+| ... | ... | ... | ... | [ ] | — |
+```
+
+**Next up:** Conductor saves `session-2-handoff.md` incorporating the full Alpha Report text (Research + Analysis + Strategy), and generates a prompt for Session 3 (Team Beta: Critics).
+
+---
+
+## Catalog of Available Frameworks (for AN-01 / AN-02)
+
+The Data Analyst selects frameworks by evaluating their relevance to the question:
+
+| Framework | Skill | When to use |
+|-----------|-------|-------------|
+| SWOT | `$swot-analysis` | Strategic position, S/W/O/T + cross-matrix |
+| TAM/SAM/SOM | `$tam-sam-som` | Market size, revenue potential |
+| Competitive Analysis | `$competitive-analysis` | Competitive landscape, threat score |
+| PEST/PESTEL | `$pest-analysis` | Macroenvironment, external factors |
+| Porter's 5 Forces | `$porters-five-forces` | Industry attractiveness |
+| BCG Matrix | `$bcg-matrix` | Portfolio analysis of business units |
+| Ansoff Matrix | `$ansoff-matrix` | Growth strategy |
+| Blue Ocean | `$blue-ocean-strategy` | Creating new market space |
+| Value Chain | `$value-chain-analysis` | Value creation chain, make-or-buy |
+| Cohort Analysis | `$cohort-analysis` | Retention, LTV by cohorts |
+| RFM Analysis | `$rfm-analysis` | Customer segmentation |
+| Unit Economics | `$unit-economics` | CAC, LTV, payback, margin |
+| Trend Analysis | `$trend-analysis` | Market trends, timing |
+| Customer Journey | `$customer-journey-mapping` | Customer journey, churn points |
+| ICP / Buyer Persona | `$icp-buyer-persona` | Target audience, personas |
+| JTBD | `$jtbd-analysis` | Client's Jobs-To-Be-Done, opportunity score |
+
+**Rule:** Minimum of 2 frameworks for the Full Pipeline (AN-01 and AN-02 must assign different ones).
+
+---
+
+## Starting Prompt Template
+
+```
+I need an in-depth analysis on: [describe the question].
+
+Context:
+- Industry: [industry]
+- Existing data: [what is available]
+- Goal: [purpose of the analysis]
+- Deadline: [if applicable]
+
+Start /analyze.
+```