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:

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

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