# 📊 Atomizer Dashboard & Reporting System — Master Plan

> **Status:** PROPOSAL | **Date:** 2026-02-14 | **Author:** Manager Agent | **For:** Antoine (CEO)

---

## Executive Summary

A file-based, agent-native dashboard and reporting system that gives Antoine real-time project visibility without leaving the existing Atomizer stack. No new infrastructure—just structured markdown, automated aggregation, and agent-generated reports.

---

## 1. Information Architecture

```
shared/
├── PROJECT_STATUS.md          ← Single source of truth (Manager-owned)
├── project_log.md             ← Append-only agent activity log
├── dashboards/
│   ├── exec-summary.md        ← CEO dashboard (auto-generated)
│   ├── technical.md           ← FEA/optimization status
│   └── operations.md          ← Agent health, queue, throughput
├── reports/
│   ├── weekly/                ← YYYY-WXX-report.md
│   ├── project/               ← Per-project closeout reports
│   └── templates/             ← Report templates (markdown)
├── data-contracts/
│   └── schemas.md             ← Field definitions for all status files
└── kpi/
    └── metrics.md             ← Rolling KPI tracker
```

**Principle:** Everything is markdown. Agents read/write natively. No database, no web server, no maintenance burden.

---

## 2. Dashboard Modules

### 2A. Executive Summary (`dashboards/exec-summary.md`)
**Audience:** Antoine | **Update frequency:** On every PROJECT_STATUS.md change

| Section | Content |
|---------|---------|
| 🚦 Project RAG | Red/Amber/Green per active project, one line each |
| 📌 Decisions Needed | Items blocked on CEO approval |
| 💰 Resource Burn | Agent token usage / cost estimate (daily/weekly) |
| 🏆 Wins This Week | Completed milestones, delivered studies |
| ⚠️ Top 3 Risks | Highest-impact risks across all projects |

**Format:** ≤30 lines. Scannable in 60 seconds.

### 2B. Technical Dashboard (`dashboards/technical.md`)
**Audience:** Technical Lead, Optimizer | **Update frequency:** Per study cycle

| Section | Content |
|---------|---------|
| Active Studies | Study name, iteration count, best objective, convergence % |
| FEA Queue | Jobs pending / running / completed / failed |
| Model Registry | Active NX models, mesh stats, last validated date |
| Optimization Curves | Tabular: iteration vs objective vs constraint satisfaction |
| Knowledge Base Delta | New entries since last report |

### 2C. Operations Dashboard (`dashboards/operations.md`)
**Audience:** Manager (self-monitoring), Mario (infra) | **Update frequency:** Hourly via cron or on-demand

| Section | Content |
|---------|---------|
| Agent Health | Last active timestamp per agent, error count (24h) |
| Message Throughput | Messages processed per agent per day |
| Queue Depth | Pending delegations, blocked tasks |
| Token Budget | Usage vs budget per agent, projected monthly |
| System Alerts | Disk, memory, process status flags |

---

## 3. Data Contracts

Every agent writing to `project_log.md` MUST use this format:

```markdown
## [YYYY-MM-DD HH:MM] agent-id | project-slug | event-type

**Status:** in-progress | completed | blocked | failed
**Summary:** One-line description
**Detail:** (optional) Multi-line context
**Metrics:** (optional) key=value pairs
**Blockers:** (optional) What's blocking and who can unblock

---
```

### Event Types (enumerated)
| Type | Meaning |
|------|---------|
| `study-start` | New optimization study launched |
| `study-iteration` | Iteration completed with results |
| `study-complete` | Study converged or terminated |
| `review-request` | Deliverable ready for review |
| `decision-needed` | CEO/human input required |
| `task-delegated` | Work handed to another agent |
| `task-completed` | Delegated work finished |
| `error` | Something failed |
| `milestone` | Phase/gate achieved |

### Dashboard Field Schema
Each dashboard section maps to specific log event types. Manager agent aggregates—no other agent touches dashboard files directly.

---

## 4. Report System

### 4A. Weekly Report (auto-generated every Friday or on-demand)
**Template:** `reports/templates/weekly-template.md`

```markdown
# Atomizer Weekly Report — YYYY-WXX

## Highlights
- (auto: completed milestones from log)

## Projects
### [Project Name]
- Status: RAG
- This week: (auto: summary of log entries)
- Next week: (auto: from PROJECT_STATUS.md planned items)
- Blockers: (auto: open blockers)

## KPIs
| Metric | This Week | Last Week | Trend |
|--------|-----------|-----------|-------|

## Agent Performance
| Agent | Messages | Tasks Done | Errors | Avg Response |
|-------|----------|------------|--------|-------------|

## Decisions Log
- (auto: from decision-needed events + resolutions)
```

### 4B. Project Closeout Report
Generated when a project reaches `completed` status. Includes full decision trail, final results, lessons learned, KB entries created.

### 4C. On-Demand Reports
Antoine can request via Discord: "Give me a status report on [project]" → Manager generates from log + status files instantly.

### 4D. PDF Generation
Use existing `atomaste-reports` skill for client-facing PDF output when needed.

---

## 5. Documentation Governance

### Two-Tier System

| Tier | Location | Owner | Mutability |
|------|----------|-------|------------|
| **Foundational** | `context-docs/` | Mario + Antoine | Immutable by agents. Amended only via CEO-approved change request. |
| **Project-Specific** | `shared/`, `memory/projects/` | Manager (gatekeeper), agents (contributors) | Living documents. Agents write, Manager curates. |

### Rules
1. **Foundational docs** (00-05, SOUL.md, protocols) = constitution. Agents reference, never edit.
2. **Project docs** = operational. Agents append to log; Manager synthesizes into status files.
3. **Dashboards** = derived. Auto-generated from project docs. Never manually edited.
4. **Reports** = snapshots. Immutable once generated. Stored chronologically.
5. **Knowledge Base** = accumulative. Grows per project via `cad_kb.py`. Never pruned without review.

### Change Control
- Protocol changes → Antoine approval → Mario implements → agents reload
- Dashboard schema changes → Manager proposes → Antoine approves → Manager implements
- New event types → Manager adds to `schemas.md` → notifies all agents via cluster message

---

## 6. Rollout Phases

| Phase | When | What | Gate |
|-------|------|------|------|
| **R0: Schema** | Week 1 | Create `data-contracts/schemas.md`, `reports/templates/`, directory structure | Manager reviews, Antoine approves structure |
| **R1: Logging** | Week 1-2 | All active agents adopt structured log format in `project_log.md` | 48h of clean structured logs from all agents |
| **R2: Exec Dashboard** | Week 2 | Manager auto-generates `exec-summary.md` from logs | Antoine confirms it's useful and accurate |
| **R3: Tech + Ops Dashboards** | Week 3 | Technical and operations dashboards go live | Tech Lead validates technical dashboard accuracy |
| **R4: Weekly Reports** | Week 3-4 | Automated weekly report generation | First 2 weekly reports reviewed by Antoine |
| **R5: KPI Tracking** | Week 4 | Rolling metrics in `kpi/metrics.md` | KPIs match reality for 2 consecutive weeks |
| **R6: PDF Reports** | Week 5+ | Client-facing report generation via atomaste-reports | First PDF passes Auditor review |

**Each phase has a go/no-go gate. No skipping.**

---

## 7. Risks & Mitigations

| # | Risk | Impact | Likelihood | Mitigation |
|---|------|--------|------------|------------|
| 1 | **Log format drift** — agents write inconsistent entries | Dashboards break | Medium | Auditor spot-checks weekly; Manager rejects malformed entries |
| 2 | **Information overload** — exec dashboard becomes too long | Antoine stops reading it | Medium | Hard cap: 30 lines. Ruthless prioritization. |
| 3 | **Stale data** — dashboards not updated after agent activity | False confidence | High | Manager updates dashboards on every log synthesis cycle |
| 4 | **Token cost explosion** — dashboard generation burns budget | Budget overrun | Low | Dashboard gen is cheap (small files). Monitor via ops dashboard. |
| 5 | **Single point of failure** — Manager agent owns all dashboards | Manager down = no visibility | Medium | Raw `project_log.md` always available; any agent can read it |
| 6 | **Scope creep** — adding features before basics work | Delayed delivery | High | Strict phase gates. No R3 until R2 is validated. |
| 7 | **File conflicts** — multiple agents writing simultaneously | Data corruption | Low | Only Manager writes dashboards; log is append-only with timestamps |

---

## 8. KPIs & Gate Rules

### KPI List

| # | KPI | Target | Measurement |
|---|-----|--------|-------------|
| K1 | Dashboard freshness | ≤1h stale | Time since last exec-summary update |
| K2 | Log compliance rate | ≥95% | % of log entries matching schema |
| K3 | Weekly report delivery | 100% on-time | Generated by Friday 17:00 EST |
| K4 | CEO read-time | ≤60 seconds | Exec summary length ≤30 lines |
| K5 | Decision backlog age | ≤48h | Max age of unresolved `decision-needed` events |
| K6 | Project status accuracy | No surprises | Zero cases where dashboard says green but reality is red |
| K7 | Agent error rate | ≤5% | Failed tasks / total tasks per agent per week |
| K8 | Report generation cost | ≤$2/week | Token cost for all dashboard + report generation |

### Gate Rules

| Gate | Criteria | Evaluator |
|------|----------|-----------|
| **G1: Schema Approved** | Antoine signs off on data contracts + directory structure | Antoine |
| **G2: Logging Stable** | 48h of compliant logs from all active agents, ≥95% schema compliance | Auditor |
| **G3: Exec Dashboard Valid** | Antoine confirms dashboard matches his understanding of project state | Antoine |
| **G4: Full Dashboards Live** | All 3 dashboards updating correctly for 1 week | Manager + Tech Lead |
| **G5: Reports Automated** | 2 consecutive weekly reports generated without manual intervention | Manager |
| **G6: System Mature** | All KPIs met for 2 consecutive weeks | Antoine (final sign-off) |

---

## Decision Required

**Antoine:** Approve this plan to begin R0 (schema creation) immediately, or flag sections needing revision.

**Estimated total effort:** ~15 agent-hours across 5 weeks. Zero new infrastructure. Zero new dependencies.