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:

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

Ask why it exists this way
- Don't assume you understand the constraints
- Components often exist for non-obvious reasons
Search for decisions
- Use get_nug with k="adr" or query terms like "decision", "choice", "architecture"
- Stale nuggets exist - verify against code when uncertain
Surface your unknowns
- Say "I don't know why X" rather than guessing
- Ask clarifying questions before diving deep

Bound your investigation
- Max 10 tool calls before summarizing
- State what you're looking for before searching
- Don't follow rabbit holes
Distinguish state from decisions
- State: current implementation details (goes stale)
- Decision: reasoning and constraints (ages better)

Multiple options with tradeoffs
- Never propose a single solution
- State assumptions explicitly
- Include "what could go wrong"
Argue against yourself
- After proposing, identify weaknesses
- Ask what the user cares about most
Smallest validating step
- What's the minimum we could build to test the direction?
- Prefer reversible over irreversible

Create nuggets for decisions, not just state
- Include WHY, not just WHAT
- Include alternatives considered
- Include constraints that shaped the choice
- Tag with project:orca

Taking 50+ steps exploring without progress. When you catch yourself:

Proposing to remove or change components without understanding their purpose. Always ask "why does this exist?" before proposing removal.

Creating nuggets that capture implementation details rather than reasoning leads to stale information that misleads future sessions.