In the studioZen — a little more clarity for ambitious work
sico studio®
Open workspace

Zen / Quality

/architecture

See the seams that make a codebase manageable.

Next mode →Template and example
npx skills@latest add sico-vibes/zen-skills --skill zen zen-architecture

Public repository release pending. Install the router with this mode for shared references and the local record writer.

Explain how the system actually works and what a proposed seam improves. Do not replace investigation with an abstract diagram.

  1. Establish the question, affected behavior and current revision. Read project rules and relevant decisions, then trace entrypoints, services, state/data ownership, adapters and responses from actual code. Include types/configuration/tests where they define the contract.
  2. Build a compact current-state map. Identify responsibilities, dependencies, public boundaries, write authority and failure/recovery paths. Separate runtime topology from folder structure. Label generated/vendor code and unavailable sources.
  3. Name concrete friction: repeated change sites, hidden coupling, ambiguous ownership, untestable IO, inconsistent vocabulary or a measured performance/recovery issue. Cite examples; do not invent abstractions for hypothetical future users.
  4. Compare retaining the current design, a focused seam/refactor and larger alternatives only when warranted. Evaluate behavior preservation, compatibility, data migration, testability, operational cost, complexity and reversibility. Prefer the narrowest boundary that owns its consumers.
  5. Propose target responsibilities and interface contracts, including error/state semantics. Show before/after maps when useful. A new interface should remove real knowledge/coupling, not just rename a wrapper.
  6. Define an incremental verification/migration plan with behavioral tests at existing seams, rollback, documentation and consequential decisions. A request for analysis is not permission to perform a broad refactor or deployment.
  7. Save an analysis DOC and, for an accepted consequential choice, an ADR DOC with source links and revisit triggers. Use the architecture comparison, record operations or initialized standalone records. Leave unapproved alternatives visibly proposed.

Completion

Return the actual call/data path, demonstrated friction, recommended change, tradeoffs and next decision/slice. Mark source-only conclusions as such. Keep the glossary aligned with the code. Do not claim a diagram proves performance, safety or a real provider run.

Example: multiple unlocked inbox rewriters justify a single mutation boundary and stable identities. Introducing several generic repositories/services without a changing consumer or concrete failure does not.