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
```markdown
## 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
```markdown
# 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
```markdown
# [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
```markdown
# 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
```markdown
# [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
```markdown
# 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
```bash
# 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:
```markdown
## 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