docs: Archive stale docs and create Atomizer-HQ agent documentation

Archive Management: - Moved RALPH_LOOP, CANVAS, and dashboard implementation plans to archive/review/ for CEO review - Moved completed restructuring plan and protocol v1 to archive/historical/ - Moved old session summaries to archive/review/ New HQ Documentation (docs/hq/): - README.md: Overview of Atomizer-HQ multi-agent optimization team - PROJECT_STRUCTURE.md: Standard KB-integrated project layout with Hydrotech reference - KB_CONVENTIONS.md: Knowledge Base accumulation principles with generation tracking - AGENT_WORKFLOWS.md: Project lifecycle phases and agent handoffs (OP_09 integration) - STUDY_CONVENTIONS.md: Technical study execution standards and atomizer_spec.json format Index Update: - Reorganized docs/00_INDEX.md with HQ docs prominent - Updated structure to reflect new agent-focused organization - Maintained core documentation access for engineers No files deleted, only moved to appropriate archive locations.
2026-02-09 02:48:35 +00:00
parent 9541958eae
commit 8d9d55356c
34 changed files with 3651 additions and 69 deletions
--- a/docs/hq/KB_CONVENTIONS.md
+++ b/docs/hq/KB_CONVENTIONS.md
@@ -0,0 +1,476 @@
+# 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