Problem/Motivation

The module's README documents usage and extension points but does not explain the architectural principles that guide design decisions. Contributors and evaluators lack context for why the module works the way it does — e.g. why the system never saves implicitly, why opaque data is protected by default, why context is delivered through tool responses rather than system prompts.

Proposed resolution

Add a "Design Philosophy" section to README.md covering the core principles:

  • On-demand context, not system prompt stuffing — context delivered via tool responses keeps the LLM's working memory focused
  • Never save implicitly — operations return unsaved entities; the caller decides persistence
  • Protect what you don't understand — opaque data preserved by default; only declared managed keys are exposed
  • Fail fast, fail clearly — two-phase validation with structured errors, paths, and hints
  • UUID-based addressing — resilient to reordering, avoids index confusion
  • Operations over round-trips — surgical edits without full re-serialization
  • Tempstore-first editing — changes staged for review before publishing
  • Workspace safety by default — active workspace required when workspaces module is enabled

Comments

tim bozeman created an issue. See original summary.

  • tim bozeman committed e0172ec5 on 1.0.x
    task: #3591631 Add design philosophy section to README
    
    By: tim bozeman
    
tim bozeman’s picture

Status: Reviewed & tested by the community » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.