Atomizer/hq/shared/skills/knowledge-base-atomizer-ext.md

# Knowledge Base — Atomizer Extension

> Extension of Mario's shared `knowledge-base` skill for Atomizer HQ's agentic workflow.
>
> **Base skill:** `/home/papa/clawd/skills/knowledge-base/SKILL.md`
> **This file:** Atomizer-specific conventions for how agents use the KB system.

---

## Key Differences from Base Skill

### Location
- **Base:** KB lives in Obsidian vault (`/obsidian-vault/2-Projects/<Project>/KB/`)
- **Atomizer:** KB lives in Atomizer repo (`/repos/Atomizer/projects/<project>/kb/`)
- Same structure, different home. Gitea-browseable, git-tracked.

### Input Sources
- **Base:** Primarily video session exports via CAD-Documenter
- **Atomizer:** Mixed sources:
  - CEO input via Slack channels
  - Agent-generated analysis (Tech Lead breakdowns, optimization results)
  - NX model introspection data
  - Automated study results
  - Video sessions (when applicable — uses base skill pipeline)

### Contributors
- **Base:** Single AI (Mario) processes sessions
- **Atomizer:** Multiple agents contribute:

| Agent | Writes To | When |
|-------|-----------|------|
| Manager 🎯 | `_index.md`, `_history.md`, `dev/gen-XXX.md` | After each project phase |
| Technical Lead 🔧 | `fea/`, `components/` (technical sections) | During analysis + review |
| Optimizer ⚡ (future) | `fea/results/`, `components/` (optimization data) | After study completion |
| Study Builder 🏗️ (future) | Study configs, introspection data | During study setup |
| CEO (Antoine) | Any file via Gitea or Slack input | Anytime |

---

## Project Structure (Atomizer Standard)

```
projects/<project-name>/
├── README.md                # Project overview, status, links
├── CONTEXT.md               # Intake requirements, constraints
├── BREAKDOWN.md             # Technical analysis (Tech Lead)
├── DECISIONS.md             # Numbered decision log
│
├── models/                  # Reference NX models (golden copies)
│   ├── *.prt, *.sim, *.fem
│   └── README.md
│
├── kb/                      # Living Knowledge Base
│   ├── _index.md            # Master overview (auto-maintained)
│   ├── _history.md          # Modification log per generation
│   ├── components/          # One file per component
│   ├── materials/           # Material data + cards
│   ├── fea/                 # FEA knowledge
│   │   ├── models/          # Model setup docs
│   │   ├── load-cases/      # BCs, loads, conditions
│   │   └── results/         # Analysis outputs + validation
│   └── dev/                 # Generation documents (gen-XXX.md)
│
├── images/                  # Screenshots, plots, CAD renders
│   ├── components/
│   └── studies/
│
├── studies/                 # Optimization campaigns
│   └── XX_<name>/
│       ├── README.md        # Study goals, findings
│       ├── atomizer_spec.json
│       ├── model/           # Study-specific model copy
│       │   └── CHANGES.md   # Delta from reference model
│       ├── introspection/   # Model discovery for this study
│       └── results/         # Outputs, plots, STUDY_REPORT.md
│
└── deliverables/            # Final client-facing outputs
    ├── FINAL_REPORT.md      # Compiled from KB
    └── RECOMMENDATIONS.md
```

---

## Agent Workflows

### 1. Project Intake (Manager)
```
CEO posts request → Manager creates:
  - CONTEXT.md (from intake data)
  - README.md (project overview)
  - DECISIONS.md (empty template)
  - kb/ structure (initialized)
  - kb/dev/gen-001.md (intake generation)
  → Delegates technical breakdown to Tech Lead
```

### 2. Technical Breakdown (Tech Lead)
```
Manager delegates → Tech Lead produces:
  - BREAKDOWN.md (full analysis)
  - Updates kb/components/ with structural behavior
  - Updates kb/fea/models/ with solver considerations
  - Identifies gaps → listed in kb/_index.md
  → Manager creates gen-002 if substantial new knowledge
```

### 3. Model Introspection (Tech Lead / Study Builder)
```
Before each study:
  - Copy reference models/ → studies/XX/model/
  - Run NX introspection → studies/XX/introspection/
  - Document changes in model/CHANGES.md
  - Update kb/fea/ with any new model knowledge
```

### 4. Study Execution (Optimizer / Study Builder)
```
During/after optimization:
  - Results written to studies/XX/results/
  - STUDY_REPORT.md summarizes findings
  - Key insights feed back into kb/:
    - Component sensitivities → kb/components/
    - FEA validation → kb/fea/results/
    - New generation doc → kb/dev/gen-XXX.md
```

### 5. Deliverable Compilation (Reporter / Manager)
```
When project is complete:
  - Compile kb/ → deliverables/FINAL_REPORT.md
  - Use cad_kb.py cdr patterns for structured output
  - Cross-reference DECISIONS.md for rationale
  - Include key plots from images/ and studies/XX/results/plots/
```

---

## Generation Conventions

Each major project event creates a new generation document:

| Gen | Trigger | Author |
|-----|---------|--------|
| 001 | Project intake + initial breakdown | Manager |
| 002 | Gap resolution / model introspection | Tech Lead |
| 003 | DoE study complete (landscape insights) | Manager / Optimizer |
| 004 | Optimization complete (best design) | Manager / Optimizer |
| 005 | Validation / final review | Tech Lead |

Generation docs go in `kb/dev/gen-XXX.md` and follow the format:
```markdown
# Gen XXX — <Title>
**Date:** YYYY-MM-DD
**Sources:** <what triggered this>
**Author:** <agent>

## What Happened
## Key Findings
## KB Entries Created/Updated
## Decisions Made
## Open Items
## Next Steps
```

---

## Decision Log Conventions

All project decisions go in `DECISIONS.md`:

```markdown
## DEC-<PROJECT>-NNN: <Title>
- **Date:** YYYY-MM-DD
- **By:** <agent or person>
- **Decision:** <what was decided>
- **Rationale:** <why>
- **Status:** Proposed | Approved | Superseded by DEC-XXX
```

Agents MUST check DECISIONS.md before proposing changes that could contradict prior decisions.

---

## Relationship to Base Skill

- **Use base skill CLI** (`cad_kb.py`) when applicable — adapt paths to `projects/<name>/kb/`
- **Use base skill templates** for component files, generation docs
- **Follow base accumulation logic** — sessions add, never replace
- **Push general improvements upstream** — if we improve KB processing, notify Mario for potential merge into shared skill

---

## Handoff Protocol

When delegating KB-related work between agents, use OP_09 format and specify:
1. Which KB files to read for context
2. Which KB files to update with results
3. What generation number to use
4. Whether a new gen doc is needed