## 🧠 Frameworks, Methodologies & Knowledge Base

### Cognitive Architecture Frameworks

#### Dual-Process Cognition (System 1 / System 2)
- **System 1 modules**: Fast pattern matching, retrieval, classification, style-consistent responses.
- **System 2 modules**: Deliberate reasoning, multi-step analysis, verification, planning.
- **Metacognitive router**: Rules for when to escalate from S1 → S2 (ambiguity, stakes, novelty, contradiction detection).

#### Layered Agent Cognitive Stack (PCA Standard Model)
```
┌─────────────────────────────────────────┐
│  INTERFACE LAYER — STYLE.md, formatting │
├─────────────────────────────────────────┤
│  IDENTITY LAYER — SOUL.md, goals, role  │
├─────────────────────────────────────────┤
│  GOVERNANCE LAYER — RULES.md, boundaries│
├─────────────────────────────────────────┤
│  CAPABILITY LAYER — SKILL.md, methods     │
├─────────────────────────────────────────┤
│  EXECUTION LAYER — prompts/*.md, tasks  │
├─────────────────────────────────────────┤
│  METACOGNITIVE LAYER — reflection loops │
└─────────────────────────────────────────┘
```

#### Reasoning Scaffolds
| Scaffold | Use Case | Implementation |
|----------|----------|----------------|
| Chain-of-Thought (CoT) | Multi-step analytical tasks | Explicit intermediate steps in SKILL or prompt |
| ReAct (Reason + Act) | Tool-using agents | Alternate thought → action → observation cycles |
| Tree-of-Thought (ToT) | Exploration under uncertainty | Branch evaluation with pruning criteria |
| Self-Consistency | High-stakes single answers | Multiple reasoning paths → consensus vote |
| Reflexion | Iterative improvement | Post-action critique → memory update → retry |

### Diagnostic Toolkit — Cognitive Failure Taxonomy
| Failure Mode | Symptom | Architectural Fix |
|--------------|---------|-------------------|
| Persona collapse | Agent breaks character under pressure | Strengthen RULES.md invariants; add identity anchors in SOUL.md |
| Reasoning drift | Logic degrades over long contexts | Chunking strategy; explicit state checkpoints; summary modules |
| Hallucination vector | Confident fabrication | Epistemic boundaries; retrieval grounding; abstention triggers |
| Context rot | Early instructions ignored | Priority hierarchy in RULES; critical constraints at top and bottom |
| Over-tooling | Excessive API calls | Decision gate before tool invocation; budget limits |
| Under-specification | Vague, generic outputs | SKILL.md templates; exemplar outputs in prompts |
| Authority confusion | Agent exceeds role scope | Least-privilege RULES; explicit escalation paths |

### Modular Persona Design Methodology (MPDM)
**Phase 1 — Cognitive Requirements Gathering**
- Stakeholders, stakes, domain, model target, latency/token budget, safety tier.

**Phase 2 — Primitive Decomposition**
- Map required behaviors to cognitive primitives: perceive, retrieve, reason, decide, act, reflect, communicate.

**Phase 3 — Module Allocation**
- Assign primitives to SOUL / STYLE / RULES / SKILL / prompts with zero overlap on invariants.

**Phase 4 — Interface Contract Definition**
- Define inputs, outputs, and handoff schemas between modules.

**Phase 5 — Failure Mode Analysis (FMA)**
- Adversarial inputs, edge cases, model-specific weaknesses.

**Phase 6 — Validation Scenarios**
- Golden-path tests, stress tests, persona-collapse tests, boundary violation tests.

**Phase 7 — Iteration & Versioning**
- Semantic versioning for soul modules; changelog per cognitive layer.

### Multi-Agent Cognitive Orchestration
- **Orchestrator pattern**: Central planner delegates to specialist agents with narrow SOULs.
- **Blackboard pattern**: Shared context store with explicit read/write permissions.
- **Pipeline pattern**: Sequential cognitive transforms with schema validation between stages.
- **Debate pattern**: Adversarial agents stress-test conclusions before synthesis.

### Context Window Strategy
- **Tier 0 (Immutable)**: RULES.md safety invariants — always loaded.
- **Tier 1 (Core)**: SOUL.md identity — loaded unless extreme budget pressure.
- **Tier 2 (Situational)**: SKILL.md + relevant prompts — loaded per task type.
- **Tier 3 (Ephemeral)**: Session state, retrieved documents — pruned aggressively.

### Evaluation Rubric for Agent Souls
| Dimension | Weight | Criteria |
|-----------|--------|----------|
| Coherence | 20% | Identity, style, rules do not contradict |
| Robustness | 20% | Handles edge cases without collapse |
| Safety | 20% | Boundaries hold under adversarial pressure |
| Efficiency | 15% | Token/latency appropriate for task |
| Auditability | 15% | Reasoning and decisions are traceable |
| Usefulness | 10% | Delivers actionable value to end user |

### Reference Domains
- Classical cognitive architectures: ACT-R, SOAR, CLARION
- Modern LLM agent patterns: LangGraph, AutoGPT-style loops, MCP tool integration
- Prompt engineering: modular souls, few-shot exemplars, constraint-first design
- Human factors: cognitive load theory, trust calibration, explainability requirements