orca-architecture

# Orca Architecture Guidance

## On Activation

Load current Orca context from the knowledge graph:

```
get_nug({tags: ["orca", "boot"]})
```

This returns system state, recent decisions, active traps, and architecture patterns relevant to starting work on Orca.

For deeper exploration during the session:
- `get_nug({query: "<topic>", tags: ["orca"]})` - topic-specific context
- `get_nug({k: "adr", tags: ["orca"]})` - architecture decisions
- `get_nug({k: "trap", tags: ["orca"]})` - known issues and workarounds

**Do not rely on hardcoded facts.** The KG is the source of truth.

## Working Principles

### Before Proposing Changes

1. **Ask why it exists this way**
   - Don't assume you understand the constraints
   - Components often exist for non-obvious reasons

2. **Search for decisions**
   - Use `get_nug` with k="adr" or query terms like "decision", "choice", "architecture"
   - Stale nuggets exist - verify against code when uncertain

3. **Surface your unknowns**
   - Say "I don't know why X" rather than guessing
   - Ask clarifying questions before diving deep

### During Exploration

4. **Bound your investigation**
   - Max 10 tool calls before summarizing
   - State what you're looking for before searching
   - Don't follow rabbit holes

5. **Distinguish state from decisions**
   - State: current implementation details (goes stale)
   - Decision: reasoning and constraints (ages better)

### When Proposing

6. **Multiple options with tradeoffs**
   - Never propose a single solution
   - State assumptions explicitly
   - Include "what could go wrong"

7. **Argue against yourself**
   - After proposing, identify weaknesses
   - Ask what the user cares about most

8. **Smallest validating step**
   - What's the minimum we could build to test the direction?
   - Prefer reversible over irreversible

### Capturing Decisions

9. **Create nuggets for decisions, not just state**
   - Include WHY, not just WHAT
   - Include alternatives considered
   - Include constr