---
type: skill
domain: architecture
---

# MASTER_ARCHITECT
> **ROLE:** System design and structural oversight
> **TRIGGER:** Invoked for new modules, major refactors, cross-cutting changes, or dependency restructuring

## Core Directive
Prevent architectural decay by enforcing structural rules before code is written. Every new file, module, or dependency must fit the existing PULSE layout or justify a deviation with evidence.

## Step-by-Step Protocol
1. **Map the blast radius:** Before any change, run `python pulse/brain/brain_query.py --query "architecture <module>"` and list every file that imports from or is imported by the target module. If the count exceeds 5, the change is HIGH RISK -- decompose it.
2. **Validate placement:** New files MUST land in the correct PULSE region. Check `Hippocampus/BRAIN_MAP.md` for the canonical directory tree. If no region fits, propose a new one with a 1-line justification in the PR description.
3. **Enforce boundaries:** No file in `Hippocampus/` should import from `pulse/`. No daemon should import from `Sensory_Input/`. Dependencies flow DOWN the stack: CLI -> Daemons -> Utilities -> Brain. Violations are blocking.
4. **Check for duplication:** Run `python pulse/brain/brain_search.py --query "<feature>"` to confirm no existing tool already does what the new code proposes. Duplicate tools are rejected.
5. **Sign off with metrics:** After implementation, verify the module meets all thresholds below. Record the architectural decision in `Hippocampus/Evidence/` via `pulse_save.py`.

## Metrics & Thresholds
- Max 300 lines per Python file (split at 250 if growing)
- Max 3 levels of directory nesting from project root
- Max 5 direct imports from other PULSE regions per file
- Every new `.py` file must have a docstring explaining its role in under 2 lines
- Zero circular imports -- test with `python -c "import <module>"` before committing

## Examples

### Good
```
PULSE/
  pulse/
    workers/pulse_worker.py        # imports from core only
    brain/brain_query.py           # imports from Hippocampus only
  Hippocampus/
    Lessons/auto_lessons.md        # no code imports at all
```
Each layer only reaches DOWN, never UP or SIDEWAYS into peer regions.

### Bad (Anti-Pattern)
```python
# In Hippocampus/Knowledge/router.py
from pulse.workers.pulse_worker import claim_task  # WRONG: brain imports daemon
from Sensory_Input.prompt_capture import capture               # WRONG: brain imports sensory
```
Brain files must never depend on runtime components. This creates boot-order failures and circular imports.

## Tools to Use
- `brain_query.py --query "architecture <area>"` -- check existing decisions
- `brain_search.py --query "<feature>"` -- find duplicate functionality
- `pulse_save.py --agent <you> --learnings "architectural decision: ..."` -- record decisions
- `hippocampus_wiring.py` -- verify brain region connectivity

## Verification
- [ ] New files placed in correct PULSE region per BRAIN_MAP.md
- [ ] No upward or circular imports introduced
- [ ] File under 300 lines, functions under 50 lines
- [ ] Existing tool duplication checked via brain_search
- [ ] Architectural decision recorded in Evidence
