Atomizer/hq/workspaces/auditor/memory/2026-02-19-spec-audit.md

# Atomizer Project Standard — Audit Report
**Auditor:** Auditor 🔍  
**Date:** 2026-02-19  
**Spec Version:** 1.0 (2026-02-18)  
**Audit Scope:** Practicality for solo FEA consultant (Antoine)

---

## EXECUTIVE SUMMARY

The specification is **well-researched and comprehensive** but **over-engineered for a solo consultant**. It proposes 13 top-level files, 5-branch KB architecture, and a 9-step instantiation protocol — this is enterprise-grade standardization for a one-person engineering practice.

**Key finding:** The spec proposes structures that don't exist in actual Atomizer projects today (M1 Mirror, Hydrotech Beam). It's aspirational, not grounded in current practice.

**Recommendation:** Adopt a **Minimum Viable Standard** (MVS) — keep what works from Hydrotech Beam's emerging structure, discard academic overhead, focus on what Antoine will actually maintain.

---

## 1. ESSENTIAL — What Antoine NEEDS

These parts deliver real value for a solo consultant:

### ✅ Self-Contained Project Folders (P1)
**Why essential:** Opening `projects/hydrotech-beam/` gives you 100% context. No hunting across repos, Notion, email. This is critical for resuming work after 2 weeks.

**Spec coverage:** ✅ Excellent  
**Keep as-is.**

### ✅ Single Entry Point (README.md or PROJECT.md)
**Why essential:** Orient yourself (or an AI agent) in <2 minutes. What is this? What's the status? Where do I look?

**Spec coverage:** ✅ Good, but split across 3 files (PROJECT.md + AGENT.md + STATUS.md)  
**Recommendation:** Merge into ONE file — README.md (proven pattern from Hydrotech Beam).

### ✅ Study Organization (studies/ with numbering)
**Why essential:** Track optimization campaign evolution. "Study 03 refined bounds from Study 02 because..."

**Spec coverage:** ✅ Excellent (numbered studies `01_`, `02_`)  
**Already in use:** Hydrotech Beam has `01_doe_landscape/`  
**Keep as-is.**

### ✅ Models Baseline (golden copies)
**Why essential:** Golden reference models. Never edit these — copy for studies.

**Spec coverage:** ✅ Good (`01-models/`)  
**Already in use:** Hydrotech has `models/`  
**Recommendation:** Drop numbering → just `models/`

### ✅ Knowledge Base (simplified)
**Why essential:** Capture design rationale, model quirks, lessons learned. Memory across studies.

**Spec coverage:** ⚠️ Over-engineered (5 branches: Design/Analysis/Manufacturing/Domain/Introspection)  
**Already in use:** Hydrotech has `kb/` with `components/`, `materials/`, `fea/`, `dev/`  
**Recommendation:** Keep Hydrotech's simpler 4-folder structure.

### ✅ Decision Log (DECISIONS.md)
**Why essential:** "Why did we choose X over Y?" Prevents re-litigating past decisions.

**Spec coverage:** ⚠️ Over-engineered (IBIS format: Context, Options, Decision, Consequences, References)  
**Already in use:** Hydrotech has simpler format (Date, By, Decision, Rationale, Status)  
**Recommendation:** Keep Hydrotech's simpler format.

### ✅ Results Tracking
**Why essential:** Reproducibility, debugging, client reporting.

**Spec coverage:** ✅ Good (`3_results/study.db`, `iteration_history.csv`)  
**Already in use:** Hydrotech has this  
**Keep as-is.**

---

## 2. CUT/SIMPLIFY — What's Over-Engineered

These parts add complexity without proportional value for a solo consultant:

### ❌ AGENT.md (separate from PROJECT.md)
**Why unnecessary:** Solo consultant = you already know the project quirks. LLM bootstrapping can live in README.md "## For AI Agents" section.

**Spec says:** Separate file for AI operational manual  
**Reality:** Hydrotech Beam has README.md + USER_GUIDE.md — no AGENT.md  
**Cut it.** Merge LLM instructions into README.md if needed.

### ❌ STATUS.md (separate dashboard)
**Why unnecessary:** For a solo consultant, status lives in your head or a quick README update. A separate file becomes stale immediately.

**Spec says:** "Update on any state change"  
**Reality:** Who enforces this? It's just you.  
**Cut it.** Put current status in README.md header.

### ❌ CHANGELOG.md (separate from DECISIONS.md)
**Why unnecessary:** DECISIONS.md already tracks major project events. CHANGELOG duplicates this.

**Spec says:** "Project evolution timeline"  
**Reality:** Git log + DECISIONS.md already provide this  
**Cut it.**

### ❌ Numbered Top-Level Folders (00-, 01-, 02-)
**Why unnecessary:** Creates cognitive overhead. "Is it `02-kb/` or `kb/`?" Alphabetical sorting is fine for 6-8 folders.

**Spec says:** "Enforces canonical reading order"  
**Reality:** Hydrotech Beam uses `kb/`, `models/`, `studies/` (no numbers) — works fine  
**Drop the numbering.** Use simple names: `context/`, `models/`, `kb/`, `studies/`, `reports/`, `tools/`

### ❌ 5-Branch KB Architecture
**Why over-engineered:** Design/Analysis/Manufacturing/Domain/Introspection is enterprise-scale. Solo consultant needs components/, fea/, materials/.

**Spec proposes:**
```
02-kb/
├── design/
│   ├── architecture/, components/, materials/, dev/
├── analysis/
│   ├── models/, mesh/, connections/, boundary-conditions/, loads/, solver/, validation/
├── manufacturing/
├── domain/
└── introspection/
```

**Hydrotech Beam reality:**
```
kb/
├── components/
├── materials/
├── fea/
│   └── models/
└── dev/
```

**Recommendation:** Keep Hydrotech's 4-folder structure. If manufacturing/domain knowledge is needed, add it as `kb/manufacturing.md` (single file, not folder).

### ❌ 00-context/ Folder (4 separate files)
**Why over-engineered:** mandate.md, requirements.md, scope.md, stakeholders.md — for a solo consultant, this lives in one CONTEXT.md file.

**Spec says:** "Each grows independently"  
**Reality:** Hydrotech has single CONTEXT.md — works fine  
**Keep as single file:** `CONTEXT.md`

### ❌ stakeholders.md
**Why unnecessary:** Solo consultant knows who the client is. If needed, it's 2 lines in CONTEXT.md.

**Cut it.**

### ❌ playbooks/ (optional, not essential)
**Why low-priority:** Nice-to-have for complex procedures, but not essential. Hydrotech has it (DOE.md, NX_REAL_RUN.md) but it's operational docs, not core structure.

**Recommendation:** Optional — include only if procedures are complex and reused.

### ❌ .atomizer/ Folder (machine metadata)
**Why premature:** This is for future Atomizer CLI tooling that doesn't exist yet. Don't create files for non-existent features.

**Spec says:** `project.json`, `template-version.json`, `hooks.json`  
**Reality:** Atomizer has no CLI that reads these yet  
**Cut it.** Add when tooling exists.

### ❌ 9-Step Template Instantiation Protocol
**Why unrealistic:** Solo consultant won't follow a formal 9-step checklist (CREATE → INTAKE → IMPORT → INTROSPECT → INTERVIEW → CONFIGURE → GENERATE → VALIDATE).

**Spec says:** "Step 5: INTERVIEW — Agent prompts user with structured questions"  
**Reality:** Antoine will create project folder, dump model files in, start working  
**Simplify:** 3 steps: Create folder, import model, run first study.

### ❌ IBIS-Inspired Decision Format
**Why too formal:** Context, Options Considered, Decision, Consequences, References — this is academic design rationale capture.

**Spec format:**
```markdown
### Context
{What situation prompted this?}
### Options Considered
1. Option A — pros/cons
2. Option B — pros/cons
### Decision
{What was chosen and WHY}
### Consequences
{Impact going forward}
### References
{Links}
```

**Hydrotech reality:**
```markdown
- **Date:** 2026-02-08
- **By:** Technical Lead
- **Decision:** Minimize mass as sole objective
- **Rationale:** Mass is Antoine's priority
- **Status:** Approved
```

**Keep Hydrotech's simpler format.**

### ❌ Session Captures (gen-NNN.md)
**Why conditional:** Only needed if using CAD-Documenter workflow (transcript + screenshots → KB processing). Not every project needs this.

**Recommendation:** Optional — include in template but don't mandate.

---

## 3. IMPROVE — What Could Be Better

### 📈 More Fluid Study Lifecycle (not 7 rigid stages)
**Issue:** The spec proposes PLAN → CONFIGURE → VALIDATE → RUN → ANALYZE → REPORT → FEED-BACK as sequential stages.

**Reality:** Solo consultant work is iterative. You configure while planning, run while validating, analyze while running.

**Improvement:** Simplify to 3 phases:
1. **Setup** (hypothesis, config, preflight)
2. **Execute** (run trials, monitor)
3. **Review** (analyze, document, feed back to KB)

### 📈 Single README.md as Master Entry
**Issue:** Spec splits PROJECT.md (overview) + AGENT.md (LLM ops) + STATUS.md (dashboard).

**Reality:** Hydrotech Beam has README.md + USER_GUIDE.md — simpler, less fragmented.

**Improvement:**
- README.md — project overview, status, navigation, quick facts
- Optional: USER_GUIDE.md for detailed operational notes (if needed)

### 📈 Make Decision Log Encouraged, Not Mandatory
**Issue:** Spec assumes DECISIONS.md is always maintained. Reality: solo consultant may skip this on small projects.

**Improvement:** Include in template but mark as "Recommended for multi-study projects."

### 📈 Simplify Folder Structure Visual
**Issue:** The spec's canonical structure is 60+ lines, intimidating.

**Improvement:**
```
project-name/
├── README.md                 # Master entry point
├── CONTEXT.md                # Requirements, scope, stakeholders
├── DECISIONS.md              # Decision log (optional but recommended)
├── models/                   # Golden copies of CAD/FEM
├── kb/                       # Knowledge base
│   ├── _index.md
│   ├── components/
│   ├── materials/
│   ├── fea/
│   └── dev/
├── studies/                  # Optimization campaigns
│   ├── 01_doe_landscape/
│   └── 02_tpe_refinement/
├── reports/                  # Client deliverables
├── images/                   # Screenshots, plots
└── tools/                    # Project-specific scripts (optional)
```

**This is ~8 top-level items** vs. spec's 13-15.

### 📈 Focus on What Antoine Already Does Well
**Observation:** Hydrotech Beam already has:
- CONTEXT.md (intake data)
- BREAKDOWN.md (technical analysis)
- DECISIONS.md (decision log)
- kb/ (knowledge base with generations)
- Numbered studies (01_)
- playbooks/ (operational docs)

**Improvement:** The standard should **codify what's working** rather than impose new structures.

---

## 4. MISSING — What's Absent

### ➕ Client Communication Log
**Gap:** No place to track client emails, meeting notes, change requests.

**Suggestion:** Add `COMMUNICATIONS.md` or `comms/` folder for client interaction history.

### ➕ Time Tracking
**Gap:** Solo consultant bills by the hour — no time tracking mechanism.

**Suggestion:** Add `HOURS.md` or integrate with existing time-tracking tool.

### ➕ Quick Wins Checklist
**Gap:** No "getting started" checklist for new projects.

**Suggestion:** Add `CHECKLIST.md` with initial setup tasks:
- [ ] Import baseline model
- [ ] Run baseline solve
- [ ] Extract baseline metrics
- [ ] Document key expressions
- [ ] Set up first study

### ➕ Design Alternatives Matrix
**Gap:** No simple way to track "Option A vs. Option B" before committing to a design direction.

**Suggestion:** Add `ALTERNATIVES.md` (simpler than full DECISIONS.md) for early-stage design exploration.

### ➕ Integration with Existing Tools
**Gap:** Spec doesn't mention CAD-Documenter, KB skills, or existing workflows.

**Suggestion:** Add section "Integration with Atomizer Workflows" showing how project structure connects to:
- CAD-Documenter (session capture → `kb/dev/`)
- KB skills (processing, extraction)
- Optimization engine (where to point `--project-root`)

---

## 5. ALIGNMENT WITH ATOMIZER PROJECTS

### M1 Mirror (Legacy Structure)
**Current:** Flat, unnumbered studies (`m1_mirror_adaptive_V11`, `m1_mirror_cost_reduction_V10`, etc.). Knowledge scattered in README.md. No decision log.

**Spec alignment:** ❌ Poor — M1 Mirror doesn't follow ANY of the spec's structure.

**Migration effort:** High — would require numbering 20+ studies, creating KB, extracting decisions from notes.

**Recommendation:** Leave M1 Mirror as-is (completed project). Use spec for NEW projects only.

### Hydrotech Beam (Emerging Structure)
**Current:** README.md, CONTEXT.md, BREAKDOWN.md, DECISIONS.md, kb/, models/, studies/ (numbered!), playbooks/.

**Spec alignment:** ⚠️ Partial — Hydrotech has SIMPLER versions of most spec elements.

**What matches:**
- ✅ Numbered studies (01_doe_landscape)
- ✅ KB folder (simplified structure)
- ✅ DECISIONS.md (simpler format)
- ✅ models/ (golden copies)
- ✅ playbooks/

**What's missing from spec:**
- ❌ No PROJECT.md/AGENT.md split (has README.md instead)
- ❌ No numbered top-level folders
- ❌ No 5-branch KB (has 4-folder KB)
- ❌ No .atomizer/ metadata

**Recommendation:** The spec should MATCH Hydrotech's structure, not replace it.

---

## 6. KEY QUESTIONS ANSWERED

### Q: Is the 7-stage study lifecycle practical for a solo consultant?
**A:** ❌ No. Too rigid. Real work is: setup → run → analyze. Not 7 sequential gates.

**Recommendation:** 3-phase lifecycle: Setup, Execute, Review.

### Q: Are numbered folders (00-context/, 01-models/, etc.) better than simple names?
**A:** ❌ No. Adds cognitive overhead without clear benefit. Hydrotech uses `kb/`, `models/`, `studies/` — works fine.

**Recommendation:** Drop numbering on top-level folders. Keep numbering ONLY for studies (01_, 02_).

### Q: Is the KB architecture (5 branches) too complex for one person?
**A:** ✅ Yes. Design/Analysis/Manufacturing/Domain/Introspection is enterprise-scale.

**Recommendation:** Use Hydrotech's 4-folder KB: `components/`, `materials/`, `fea/`, `dev/`.

### Q: Is DECISIONS.md with IBIS format realistic to maintain?
**A:** ⚠️ IBIS format is too formal. Hydrotech's simpler format (Date, By, Decision, Rationale, Status) is realistic.

**Recommendation:** Use Hydrotech's format. Make DECISIONS.md optional for small projects.

### Q: What's the minimum viable version of this spec?
**A:** See Section 7 below.

---

## 7. MINIMUM VIABLE STANDARD (MVS)

Here's the **practical, solo-consultant-friendly** version:

```
project-name/
│
├── README.md                 # Master entry: overview, status, navigation
├── CONTEXT.md                # Intake: client, requirements, scope
├── DECISIONS.md              # Decision log (optional, recommended for multi-study)
│
├── models/                   # Golden copies — never edit directly
│   ├── README.md             # Model versions, how to open
│   └── baseline/             # Baseline solve results
│
├── kb/                       # Knowledge base
│   ├── _index.md             # KB overview + gap tracker
│   ├── components/           # One file per component
│   ├── materials/            # Material data
│   ├── fea/                  # FEA model docs
│   │   └── models/
│   └── dev/                  # Session captures (optional)
│
├── studies/                  # Numbered optimization campaigns
│   ├── 01_doe_landscape/
│   │   ├── README.md         # Hypothesis, config, conclusions
│   │   ├── atomizer_spec.json
│   │   ├── 1_setup/
│   │   └── 3_results/
│   └── 02_tpe_refinement/
│
├── reports/                  # Client deliverables
├── images/                   # Screenshots, plots, renders
└── tools/                    # Custom scripts (optional)
```

**Top-level files:** 3 (README, CONTEXT, DECISIONS)  
**Top-level folders:** 6 (models, kb, studies, reports, images, tools)  
**Total:** 9 items vs. spec's 13-15

**What's different from the spec:**
- ❌ No PROJECT.md/AGENT.md/STATUS.md split → single README.md
- ❌ No numbered folders (00-, 01-, 02-) → simple names
- ❌ No 5-branch KB → 4-folder KB (proven pattern)
- ❌ No 00-context/ folder → single CONTEXT.md
- ❌ No CHANGELOG.md → Git log + DECISIONS.md
- ❌ No .atomizer/ metadata → add when tooling exists
- ❌ No stakeholders.md → lives in CONTEXT.md
- ✅ Keep numbered studies (01_, 02_)
- ✅ Keep DECISIONS.md (simpler format)
- ✅ Keep KB structure (Hydrotech pattern)

---

## 8. RISKS & ASSUMPTIONS

### Risks
1. **Spec is aspirational, not validated** — proposed structures don't exist in real projects yet
2. **Maintenance burden** — 13 files to keep updated vs. 3-4 for MVS
3. **Template complexity** — 9-step instantiation too formal for solo work
4. **Over-standardization** — solo consultant needs flexibility, not enterprise rigor

### Assumptions
1. Antoine will NOT follow formal 9-step instantiation protocol
2. Antoine will NOT maintain separate STATUS.md (goes stale immediately)
3. Antoine WILL maintain DECISIONS.md if format is simple (Hydrotech proof)
4. Antoine WILL use numbered studies (already in Hydrotech)
5. Multi-file KB branches (Design/Analysis/etc.) are overkill for 1-5 component projects

---

## 9. RECOMMENDATIONS

### For Immediate Action
1. ✅ **Adopt MVS** — Use Hydrotech Beam's structure as the template (it's already working)
2. ✅ **Codify existing practice** — Spec should document what Antoine ALREADY does, not impose new patterns
3. ✅ **Simplify entry point** — Single README.md, not 3 files (PROJECT + AGENT + STATUS)
4. ✅ **Drop numbered top-level folders** — Use simple names (models/, kb/, studies/)
5. ✅ **Keep simple KB** — 4 folders (components/, materials/, fea/, dev/), not 5 branches
6. ✅ **Keep simple DECISIONS.md** — Hydrotech format (Date, By, Decision, Rationale, Status)

### For Future Consideration
1. ⏳ Add `COMMUNICATIONS.md` for client interaction log
2. ⏳ Add `HOURS.md` for time tracking
3. ⏳ Add `.atomizer/` metadata when CLI tooling exists
4. ⏳ Add playbooks/ only for complex projects
5. ⏳ Add BREAKDOWN.md (Hydrotech has this — spec missed it!)

### For Long-Term Evolution
1. 🔮 If Atomizer grows to 3-5 engineers → revisit enterprise features (5-branch KB, formal lifecycle)
2. 🔮 If project complexity increases (10+ studies) → revisit numbered top-level folders
3. 🔮 If client deliverables become complex → revisit report generation protocol

---

## 10. CONFIDENCE & NOTES

**Confidence:** HIGH

**Why:**
- ✅ Audited actual Atomizer projects (M1 Mirror, Hydrotech Beam)
- ✅ Compared spec to real practice (spec is aspirational, not grounded)
- ✅ Identified working patterns (Hydrotech's emerging structure)
- ✅ Practical experience: solo consultants don't maintain 13-file templates

**Notes:**
- The spec author (Manager 🎯) did excellent research (NASA-STD-7009, ASME V&V 10, IBIS/QOC, industry standards) but optimized for **enterprise rigor** not **solo consultant pragmatism**
- Hydrotech Beam is already 80% of the way to a good standard — codify THAT, don't replace it
- The spec's fictive validation project (ThermoShield Bracket) is well-designed but proves the structure is complex (13 top-level items)

**Follow-ups:**
1. Present MVS to Antoine for approval
2. Update Hydrotech Beam to MVS (minimal changes needed)
3. Create lightweight project template based on MVS
4. Archive full spec as "Future Enterprise Standard" for if/when Atomizer scales

---

**END OF AUDIT**