# ADR 001: Role Split Across Equipment Service System **Status:** Accepted **Date:** 2026-04-26 **Decision-makers:** Sam (coordinator), LT180 chat session, Jetski (Sea-Doo GTX DI 2001) chat session **Implemented by:** Claude Code (infrastructure provisioning) --- ## Context Sam runs equipment diagnostic and service work across multiple equipment items (John Deere LT180 lawn tractor, Sea-Doo GTX DI 2001 jetski, Four Winns boat, future additions). Work is performed across multiple Claude chat sessions — one per equipment item — with infrastructure work potentially handled by Claude Code, and the management app (/manage PWA) as a possible eventual home for the consolidated knowledge base. Without an explicit role split, the system risks: - Multiple Claude sessions editing the same files with no source-of-truth discipline - Equipment chats making architectural decisions outside their tool capabilities (no filesystem, no git, no build) - Claude Code attempting diagnostic content generation, losing the accumulated context that lives in equipment chat sessions - Sam re-explaining methodology and architecture from scratch in every new chat This ADR establishes the role boundaries to prevent those failure modes. --- ## Decision Three roles are defined with explicit boundaries: ### Equipment chats (per-equipment Claude sessions) **Owns:** Diagnostic content, service procedures, versioned HTML guides, handoff blocks, photos, source citations. **Does not own:** Repo structure, deployment pipeline, app schema, or any architectural decision about how the knowledge base is stored or served. **Rationale:** Diagnostic work depends on accumulated context — EPA label decodes, image processing of HIN plates, hypothesis ranking refined through conversation, errata documented across the session. Reconstructing that context from a fresh session is lossy and slow. Equipment chats also have web_search and image_search tools well-suited to research and verification work. ### Claude Code **Owns:** Repo provisioning, file structure, git workflow, deploy pipeline (Cloudflare Pages or alternative), CI configuration, /manage Equipment tab integration when scoped, schema design, migrations. **Does not own:** Diagnostic content generation, equipment-specific procedure authoring. **Rationale:** Claude Code has filesystem access, git, build/CI capability, and tight iteration loops on code with real feedback. These are the right tools for infrastructure work. Equipment chats can describe what they want from infrastructure but cannot test or commit changes. ### Sam (coordinator) **Owns:** Workstream prioritization, "done enough" calls on guide finalization, methodology revision approvals, decisions about scope expansion (new equipment, new tooling), conflict resolution between Claude sessions when they disagree. **Does not own (by intent):** Direct content generation (delegated to equipment chats), direct infrastructure provisioning (delegated to Claude Code). **Rationale:** The coordinator role cannot be automated into either Claude type without losing the human judgment about what matters and what's done. Keeping it explicit prevents Sam from being absorbed into either tool's workflow. --- ## Consequences ### Positive - **Single source of truth per artifact.** Each file has exactly one Claude type that edits it. No conflicting edits. - **Tool-fit alignment.** Each role uses tools matched to its work — diagnostic chats use web_search and image processing, Claude Code uses git and filesystem, Sam uses prioritization judgment. - **Context preservation.** Equipment chats retain diagnostic context across the diagnostic phase; Claude Code doesn't re-derive it. - **Methodology consistency.** The methodology block applies uniformly across all equipment chats; Claude Code is constrained to architectural decisions only. - **Repo as durable substrate.** All work product survives any individual chat session ending. ### Negative - **Coordination overhead.** Sam is the bridge between sessions; no direct chat-to-chat communication. Mitigated by repo-hosted handoff blocks and methodology. - **Initial setup cost.** Repo + deploy pipeline + first guide migration takes effort before the system pays off. - **Methodology drift risk.** If individual equipment chats interpret methodology differently, output diverges. Mitigated by canonical METHODOLOGY.md in repo with revision history. ### Neutral - New equipment types follow the same template — onboarding cost per new equipment is low. - Future migration of guides into /manage app's Equipment tab is unblocked but not required by this decision. --- ## Alternatives considered ### Alternative 1: Single Claude session per equipment, no Claude Code involvement Each equipment chat handles its own infrastructure (e.g., outputs HTML files Sam manually places in a folder). No repo, no deploy pipeline. **Rejected because:** Equipment chats can't test deploys, can't iterate on infrastructure, and can't commit to git. Sam ends up doing all the infrastructure work manually, which doesn't scale across equipment items. ### Alternative 2: Claude Code handles everything Claude Code does diagnostic content generation in addition to infrastructure. **Rejected because:** Claude Code starting fresh on diagnostic work loses the accumulated context that lives in equipment chats (label decodes, hypothesis refinement, errata trail). The translation cost from equipment chat to Claude Code is high enough that direct equipment chat ownership is more efficient. ### Alternative 3: Equipment chats produce content directly into the /manage app Skip the repo entirely and treat the management app as the source of truth. **Rejected because:** The /manage app integration is non-trivial work (schema, rendering, search) and shouldn't block content generation. Repo-first lets content production proceed in parallel with infrastructure work, with eventual migration into the app as a separate workstream. --- ## Boundary enforcement To make the role split sticky: 1. METHODOLOGY.md (this repo) explicitly documents the boundaries. 2. Session-opening template directs equipment chats to web_fetch the methodology, including the role split. 3. Claude Code's onboarding brief explicitly states it should not generate diagnostic content from scratch. 4. Sam reviews any work product that crosses boundaries (e.g., an equipment chat proposing infrastructure changes) and decides whether to escalate to Claude Code. --- ## Revision history | Date | Change | Author | |---|---|---| | 2026-04-26 | Initial decision, ratified by LT180 + jetski chats | Sam (coordinator) | --- ## Source exchange The reasoning for this ADR was developed through a peer exchange between the LT180 and jetski equipment chats, with Sam as bridge. The full exchange is preserved in the repo for reference; key messages are available on request. The exchange itself demonstrates the coordination model the ADR formalizes — Sam-mediated, asynchronous, with each session contributing within its scope of expertise.