Atomizer/docs/hq/KB_CONVENTIONS.md

Knowledge Base Conventions

Version: 1.0
Created: February 2026
Scope: Atomizer-HQ Knowledge Base Usage

---

Core Principle: Accumulation, Never Replacement

The Knowledge Base (KB) is the memory of Atomizer-HQ. Every insight, result, and lesson learned gets added to the KB. Never replace or delete existing knowledge — only append and refine.

Why Accumulation Matters

• Prevents re-work — Don't rediscover the same constraints
• Tracks evolution — See how understanding developed over time
• Maintains context — Know why decisions were made
• Enables learning — Pattern recognition across projects

---

Knowledge Base Structure

Two-Level KB System

1. Global KB (knowledge_base/)

• Cross-project insights
• General FEA principles
• Reusable component knowledge
• Shared lessons learned

2. Project-Specific KB (projects/[project]/kb/)

• Project-specific findings
• Component behavior in this application
• Client-specific constraints
• Study-specific insights

KB Directory Structure

kb/
├── README.md                     # Navigation and conventions
├── components/                   # Component-specific knowledge
│   ├── [component-name].md      # Accumulated component insights
│   └── manufacturing-constraints.md
├── materials/                    # Material property knowledge  
├── fea/                         # FEA-specific knowledge
│   ├── models/                  # Modeling conventions
│   ├── load-cases/              # Load case documentation
│   └── results/                 # Results interpretation
├── dev/                         # Development knowledge
│   ├── lessons-learned.md       # Process insights
│   ├── optimization-insights.md # What works/doesn't work
│   └── process-improvements.md  # Workflow refinements
└── [domain-specific]/           # Custom categories as needed

---

Generation Tracking System

Every KB entry must track when and why knowledge was added. This creates a timeline of understanding evolution.

Generation Format

## Generation N: [Descriptive Title] ([Date])
**Context**: [What study/analysis led to this]  
**Agent**: [Who contributed this knowledge]  
**Confidence**: [High/Medium/Low]

[Knowledge content...]

### Key Insights
- [Insight 1]
- [Insight 2]

### Implications
- [How this affects future work]
- [What should be investigated next]

Example: Component Knowledge Evolution

# hydraulic-cylinder-mount.md

## Generation 1: Initial CAD Analysis (2026-02-01)
**Context**: Baseline model review  
**Agent**: Technical Lead  
**Confidence**: High

### Component Overview
- Function: Mount hydraulic cylinder to main frame
- Critical loads: 15kN axial, 5kN lateral
- Material: Steel A36 (client requirement)
- Manufacturing: Welded fabrication

### Key Features
- 4 bolt mounting pattern
- Integrated gusset plates for lateral stability
- Access clearance for maintenance

## Generation 2: First FEA Results (2026-02-03)
**Context**: Baseline validation study  
**Agent**: Optimizer  
**Confidence**: High

### Stress Analysis Results
- Maximum stress: 185 MPa at bolt interface
- Critical location: Upper bolt hole edge
- Safety factor: 1.45 (acceptable but tight)

### Key Insights
- Bolt pattern creates stress concentration
- Current design marginal for peak loads
- Fillet radius at gusset transition critical

### Implications
- Consider larger fillet radii in optimization
- Investigate bolt pattern alternatives
- Monitor fatigue potential at stress concentration

## Generation 3: Optimization Insights (2026-02-05)
**Context**: Stress minimization study results  
**Agent**: Post-Processor  
**Confidence**: Medium

### Optimization Findings
- Fillet radius optimization: 5mm → 8mm reduced stress 18%
- Gusset thickness optimization: 12mm → 15mm reduced stress 12%
- Combined effect: 28% stress reduction (185 → 133 MPa)

### Unexpected Behaviors
- Material redistribution created new stress concentration at base
- Larger fillets improved stress but increased mass significantly
- Sweet spot: 7mm fillet radius for stress-mass balance

### Key Insights
- Component responds well to local geometry changes
- Global stiffness less important than local stress concentrators
- Mass penalty acceptable for stress improvement

### Implications
- 7mm fillet radius recommended for similar mounts
- Always check for new stress concentrations after optimization
- Consider this component pattern for future hydraulic mounts

---

Component File Format

Each component gets its own KB file with standardized sections.

Standard Component Template

# [component-name].md

## Component Overview
**Function**: [Primary purpose]  
**Critical Loads**: [Key loading conditions]  
**Material**: [Current material choice]  
**Manufacturing**: [Fabrication method]  

## Behavioral Characteristics
[How this component behaves under various conditions]

## Design Sensitivities
[What design parameters most affect performance]

## Optimization Insights
[What works well, what doesn't, from studies]

## Constraints and Limitations
[Manufacturing, geometric, material constraints]

## Lessons Learned
[Key insights that affect future designs]

## Related Components
[Links to other components that interact with this one]

---
[Then generations as above...]

---

FEA KB Structure

FEA knowledge is organized by simulation aspect, not by study.

FEA Knowledge Categories

Models (fea/models/):

• Meshing conventions and best practices
• Boundary condition approaches
• Material model selection
• Modeling assumptions and simplifications

Load Cases (fea/load-cases/):

• Operating condition definitions
• Load magnitudes and distributions
• Safety factors and design criteria
• Dynamic vs. static considerations

Results (fea/results/):

• Stress criteria and failure modes
• Results interpretation guidelines
• Post-processing best practices
• Validation methods

Example: FEA Models Knowledge

# meshing-conventions.md

## Generation 1: Initial Meshing Approach (2026-02-01)
**Context**: Project setup  
**Agent**: Technical Lead  
**Confidence**: High

### Standard Mesh Settings
- Element type: Quadratic tetrahedral (10-node)
- Element size: 5mm global, 2mm at stress concentrations
- Mesh quality: Aspect ratio < 3, Jacobian > 0.6

### Refinement Criteria
- Refine at fillets, holes, geometric transitions
- Use mesh convergence study for critical components
- Target: <5% stress change with 50% size reduction

## Generation 2: Mesh Sensitivity Findings (2026-02-03)
**Context**: Baseline validation convergence study  
**Agent**: Technical Lead  
**Confidence**: High

### Key Findings
- Current mesh adequate for global stress (2% error vs. fine mesh)
- Local stress concentrations require 1mm elements for convergence
- Contact regions need special attention (0.5mm elements)

### Updated Guidelines
- Global: 5mm remains adequate
- Stress concentrations: 1mm elements
- Contact zones: 0.5mm elements
- Always run convergence check on critical locations

### Implications
- Computational cost manageable with selective refinement
- Focus refinement efforts on actual critical locations
- Standard mesh appropriate for optimization studies

---

Material Knowledge Format

Material knowledge tracks property validation and selection criteria.

Material Template

# [material-type]-properties.md

## Material Overview
**Designation**: [Standard designation]  
**Grade**: [Specific grade if applicable]  
**Condition**: [Heat treatment, condition]  

## Validated Properties
[Properties confirmed through testing or analysis]

## Design Allowables  
[Properties used for design criteria]

## Application History
[Where and how this material has been used successfully]

## Limitations and Considerations
[When this material should/shouldn't be used]

---
[Then generations with specific validation results]

---

Agent Contribution Guidelines

All Agents: Basic KB Responsibilities

1. Read existing KB before starting work (avoid duplicate effort)
2. Add findings immediately after analysis (don't wait)
3. Use generation format for all contributions
4. Link to source studies when relevant

Specific Agent Roles

Technical Lead:

• Component characterization
• FEA modeling conventions
• Material property validation
• Engineering judgment and trade-offs

Optimizer:

• Optimization results and insights
• Parameter sensitivity findings
• Algorithm performance notes
• Convergence characteristics

Post-Processor:

• Results interpretation
• Visualization insights
• Analysis methodology
• Validation approaches

Manager:

• Process lessons learned
• Project management insights
• Resource allocation learnings
• Timeline and coordination notes

---

Mario's Shared KB Skill Integration

Relationship to Global System

The Atomizer KB system extends Mario's global Knowledge Base skill with domain-specific conventions.

Global KB Skill (/home/papa/clawd/skills/knowledge-base/SKILL.md):

• Core KB processing algorithms
• CDR (Critical Design Review) generation
• Knowledge extraction and summarization
• Cross-project insight correlation

Atomizer Extension (/home/papa/atomizer/shared/skills/knowledge-base-atomizer-ext.md):

• FEA-specific knowledge patterns
• Component behavior tracking
• Optimization insight accumulation
• Agent workflow integration

Extension File Format

# knowledge-base-atomizer-ext.md

## FEA Knowledge Patterns
[Specific patterns for FEA knowledge organization]

## Component Tracking Extensions
[How to track component behavior across projects]

## Optimization Insight Formats
[Standardized formats for optimization results]

## Agent Integration Points
[How different agents contribute to KB]

Using the Global KB CLI

# Check KB status for project
cad_kb.py status projects/hydrotech-beam/kb

# Generate project context summary
cad_kb.py context projects/hydrotech-beam/kb --output summary.md

# Create CDR content from accumulated knowledge
cad_kb.py cdr projects/hydrotech-beam/kb --milestone "Design Optimization Complete"

---

Quality Standards

Knowledge Quality Criteria

1. Specific and Actionable — "Increase fillet radius to 7mm" not "Make fillets bigger"
2. Context-Rich — Explain why, not just what
3. Traceable — Link to source studies, analyses, decisions
4. Timestamped — Generation tracking for all entries
5. Validated — Distinguish between hypothesis and confirmed results

Common Quality Issues

❌ Vague: "Design performed well"
✅ Specific: "Stress reduced from 185 MPa to 133 MPa with 7mm fillet radius"

❌ No context: "Use steel for this part"
✅ Context: "Steel A36 selected for cost; aluminum would reduce mass but exceed budget"

❌ Missing generation: Old content with no timestamp
✅ Generation tracked: "Generation 3: Optimization Results (2026-02-05)"

---

KB Maintenance and Review

Regular Maintenance Tasks

Weekly (Manager):

• Review new KB contributions for quality
• Identify missing knowledge gaps
• Ensure generation tracking compliance

Per Project (Technical Lead):

• Consolidate project-specific insights
• Promote reusable knowledge to global KB
• Archive completed project KB

Per Study (All agents):

• Document study-specific insights immediately
• Update relevant component/material knowledge
• Note any contradictions with existing knowledge

Knowledge Conflict Resolution

When new knowledge contradicts existing knowledge:

1. Don't delete the conflicting knowledge
2. Add new generation with updated understanding
3. Explain the difference — why did understanding change?
4. Flag for review — may indicate systematic issue

Example:

## Generation 4: Revised Load Understanding (2026-02-10)
**Context**: Additional client requirements revealed higher loads  
**Agent**: Technical Lead  
**Confidence**: High

**NOTE**: This generation revises Generation 2 load assumptions.

### Updated Load Requirements
- Previous: 15kN axial (Generation 2)
- Revised: 22kN axial (new client requirement)
- Impact: Safety factor drops from 1.45 to 0.98 (inadequate)

### Implications
- Current design no longer adequate
- Need significant reinforcement or redesign
- All stress calculations in Generation 2-3 need updating

---

Examples and Templates

Component Knowledge Example

See projects/hydrotech-beam/kb/components/beam-support-bracket.md for full example

Material Knowledge Example

See projects/hydrotech-beam/kb/materials/steel-a36-properties.md for full example

FEA Knowledge Example

See projects/hydrotech-beam/kb/fea/models/meshing-conventions.md for full example

---

Best Practices Summary

Writing Effective KB Entries

1. Write immediately — Don't accumulate for later
2. Be specific — Quantitative when possible
3. Include context — Why was this learned?
4. Link studies — Reference source analysis
5. Use generations — Track knowledge evolution
6. Update implications — How does this affect future work?

Using Existing KB

1. Read before starting — Don't duplicate effort
2. Search across projects — Similar components may exist
3. Follow patterns — Use established insights
4. Build on previous work — Reference and extend
5. Question contradictions — Flag inconsistencies

Maintaining KB Quality

1. Review contributions — Ensure quality standards
2. Consolidate related entries — Avoid fragmentation
3. Update implications — Keep forward-looking guidance current
4. Archive completed projects — Promote reusable insights to global

---

Last updated: February 2026