Atomizer/hq/workspaces/manager/memory/projects/dashboard-reporting-masterplan.md

📊 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:

## [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

# 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.