# Session Prelude Kind-specific behavior spec for sessions opening against `METHODOLOGY.md`. The methodology defines universal rules; this document defines how those rules specialize per session kind, plus the bootstrap mechanics every session executes on receipt of an opener. **Version:** 1.0.1 **Last updated:** 2026-04-28 **Maintained in:** `samesolutions-equipment-service` repo **Companion to:** `METHODOLOGY.md` v1.2 --- ## Session bootstrap ### The opener Every session begins with a five-field opener from Sam: ``` Same Solutions session. Kind: [equipment | customer | property | personal | meta] ID: [entity slug — e.g., fourwinns-h190, customer-aceves] Repo: https://samesolutions-equipment-service.pages.dev Context: [one sentence on what's new this session] ``` If the chat receives a first message that does not match this pattern and is not an obvious continuation of an existing session, the session must respond with: "Looks like a new session without protocol. Should I fetch methodology and treat this as kind=[guess]/id=[guess]? Confirm or correct." This is the methodology's protocol-enforcement clause, surfaced session-side. ### URL seeding `web_fetch` in chat sandboxes accepts URLs that have appeared in user input or prior search results. The opener's `Repo:` field places the canonical base URL in the user input, but this alone does not guarantee descendant paths are fetchable — the sandbox treats each URL as a discrete permission grant, not a tree. Therefore: the session, on receipt of an opener, must extract the base URL and fetch each canonical path explicitly, in the order listed below. Each successful fetch seeds that URL into the fetchable set; subsequent fetches against descendant paths inherit from those seeds. When opening a new equipment kind for the first time, Sam should include the canonical paths inline in the opener's `Context:` field if the session shows signs of failing to construct them correctly. Convention is for sessions to know how to construct paths; reality is that this assumption breaks under sandbox constraints. This convention may be revisable when `web_fetch` sandbox behavior changes. Track via DR if the constraint relaxes. ### Bootstrap fetch order In order, with stop-on-fail behavior described per step: 1. **Methodology** (universal, mandatory): `/METHODOLOGY.md` Stop on fail — without methodology, no further work proceeds. Announce per Methodology Principle 4. See "Failure class differentiation" below. 2. **This document** (universal, mandatory): `/SESSION-PRELUDE.md` Stop on fail — without prelude, kind-specific behavior is ungrounded. 3. **Entity index** (kind-specific, expected when entity exists): `/index//.md` A 404 here is informational, not a failure — it means this is a new entity. Proceed with empty entity context. A 403 or 5xx is a failure and gets announced. 4. **Pending decision requests** (universal, may be empty): `/architecture/pending/` Empty directory is the common case. Any DRs found get scanned for relevance to this session's kind and ID; relevant DRs are surfaced to Sam in the session's first response. Errors get announced. 5. **Latest guide for this entity** (kind-specific, optional): For `kind: equipment`, fetch the highest-numbered guide in `guides//` if any exists. Skip for other kinds (their deliverables aren't versioned HTML guides). After bootstrap, the session asks the user only what cannot be determined from the fetched substrate. --- ## Tool-and-substrate primacy (Principle 8 anchor) Per Methodology Principle 8 (Use tools and substrate, not users), the session must verify before any action whether the work can be performed by a tool or substrate operation it has access to. If yes, the session executes; it does not delegate to the user. The user is asked only when the action requires capability the session does not have (physical inspection, repo writes via Claude Code, decisions resolving DRs, judgment on scope/priority). This rule is kind-agnostic. It applies to equipment, customer, property, personal, and meta sessions equally. See "Tool inventory" below for the concrete capability list every session checks against before delegating. **Try first, announce if blocked.** When a tool's success is uncertain, the session attempts execution and announces if it fails — including which tool was attempted and what the failure was — rather than asking the user to perform the work in advance. Examples: - Need to inspect a file the user uploaded → use `view` or `bash_tool`, not "can you open it and tell me what's in it?" - Need to verify a current fact → use `web_search`, not "can you confirm X is still true?" - Need to move content between sessions → write a DR (substrate-mediated), not "can you paste this in the other chat?" - Need to recall something earlier in the session → re-read context, not "what did you say about X earlier?" **Structurally irreducible delegation.** One delegation pattern is currently irreducible at this scale: chat sessions cannot write to git directly, and Claude Code cannot fetch from chat output. Sam transports session output to Claude Code for commit. This is not bypass — it is the only possible flow given the tool asymmetry. Future MCP-based shared storage may reduce this delegation; it is not worth the setup tax at the current rate of inter-session transfer (~1/week). Revisit when transfer rate hits ~5/week. --- ## Tool inventory Sessions in this system have, at minimum, the following capabilities. Before delegating to the user, the session checks this list: ### File and content operations - `view` — read text files, image files, directory listings from the chat sandbox - `bash_tool` — execute shell commands including grep/find/awk/sed for content inspection - `create_file` / `str_replace` — write or edit files in the sandbox ### External information - `web_fetch` — retrieve URLs that have appeared in user input or prior search results - `web_search` — search the open web (when enabled in the chat) - `image_search` — find images on the web (when enabled in the chat) ### Image and visual - `view` on image files — Claude can see images directly - Image processing via `bash_tool` — OpenCV, PIL, etc., available in sandbox ### Substrate (cross-session) operations - `web_fetch` against canonical repo URLs once seeded — methodology, prelude, indices, guides, pending DRs - DR commit (via Claude Code, user-mediated due to no direct git access — this delegation is structurally required, not bypass; see "Tool-and-substrate primacy" above) ### Conversation state - The session's own context window — anything the user has said, anything the session has produced, anything fetched. Re-reading this is not delegation; it is the session doing its job. ### What the user uniquely provides (delegation here is correct, not bypass) - Physical inspection (photos, measurements, equipment access, plate readings) - Triggering Claude Code commits (substrate writes) - Resolution decisions on DRs - Scope, priority, "done enough" judgment - Information the user holds outside any system Claude can reach **Tool inventory hygiene rule:** if a session is uncertain whether a capability exists, the session checks before delegating. The cost of attempting a tool call and failing is far lower than the cost of unnecessary delegation. The default bias is "try, then announce if blocked." **Per-kind divergence is not real today** — all kinds run with the same default toolset on Sam's claude.ai account. One inventory covers all sessions. Split per-kind only when actual tool availability diverges (e.g., customer chats get a customer-database MCP that equipment chats don't). --- ## Failure class differentiation Substrate fetch failures fall into four classes. Different classes warrant different responses. **Class 1 — Sandbox/permissions error.** Tool returns `PERMISSIONS_ERROR` or equivalent. URL is well-formed but not in the fetchable set. Substrate is fine; this is a chat-environment limitation. Response: announce, request the user to seed the URL by including it in their next message or via paste-fallback. Not urgent — bootstrap can proceed once seeded. **Class 2 — Genuine substrate failure.** Tool returns 404 against an expected canonical path (e.g., `METHODOLOGY.md` missing), 403 where Cloudflare Access bypass should apply, or 5xx errors. The substrate itself is broken. Response: announce with urgency flag; recommend Sam check Claude Code's recent commits or deploy state. Bootstrap may need to abort. **Class 3 — Expected absence.** 404 against a path that may legitimately not exist yet — entity index for a new entity, empty `architecture/pending/`, no prior guide for new equipment. Response: silent acceptance, proceed with empty context for that fetch. **Class 4 — Session web_fetch cache serving stale content.** Tool returns content that doesn't match current canonical state at the URL (e.g., methodology header shows v1.1 when canonical is v1.2; substrate independently verified current via incognito browser or Claude Code curl). Cause: Anthropic web_fetch caches responses keyed on URL within a session. Files re-edited at the same URL serve from cache rather than re-fetching. Distinguishing from Class 1: Class 1 is "URL not in fetchable set" (`PERMISSIONS_ERROR`); Class 4 is "URL fetches successfully but returns outdated content." Distinguishing from Class 2: Class 2 is genuine substrate failure (deploy broken, 404, 403); Class 4 has substrate fine, only the session's view of it is stale. Response: re-fetch with a query string (e.g., `?v=` or `?refresh=1`). Different URL bypasses cache. If still stale, escalate to Class 2 diagnostic. Distinguishing these matters because Class 1 blocks until Sam acts, Class 2 blocks until infrastructure is fixed, Class 3 doesn't block at all, and Class 4 is self-resolvable by the session via URL cache-busting. --- ## Kind-specific behavior The methodology applies universally; these sections describe how each kind specializes the universal rules. Tone (technical peer, concise, push-back-with-evidence) is constant across kinds. ### Kind: equipment **Purpose:** diagnostic and service work on physical equipment owned by Sam or a customer. Examples: LT180 lawn tractor, Sea-Doo GTX DI 2001 jetski, Four Winns H190 boat. **Deliverable:** versioned HTML guide rendered against `templates/equipment-service-guide-template.html`. Filename: `-service-guide-v.html` in `guides//`. **Required artifacts during session:** - Diagnostic Hypothesis Log (DHL) when 2+ candidate causes exist for a symptom. Path: `guides//diagnostic-logs/DHL-NNN-.md`. Skip for single-cause obvious diagnoses. - Handoff block at session end. Path: `handoff-blocks/-.md`. **Verification priorities specific to this kind:** - Equipment identification first — VIN/HIN/serial plate, EPA label, model tag. Decode before recommending procedures or parts. - OEM service manual is the canonical source for torque, capacity, gap, compression specs. Forum confirmation is acceptable for symptom-to-failure-mode mapping; not acceptable as a primary spec source. - Part numbers: search manufacturer's parts catalog or authorized dealer documentation. Mark `// UNVERIFIED` until cross-checked. Memory-recalled part numbers are unacceptable in finalized guide content. **Common failure modes for this kind:** - Engine family / configuration misidentification leading to procedures that apply to a different model. Mitigation: equipment ID verification is step zero, before any procedure work. - Part number drift across model years. Mitigation: cite the source revision date with the part number. - Diagnostic capitulation under pushback. Mitigation: DHL discipline plus methodology Principle 3. **Out of scope:** - Customer billing for equipment work (handled by /manage app, not this guide). Reference customer ID if relevant; do not generate quote/invoice content here. ### Kind: customer **Purpose:** customer-facing service work where the deliverable lives in /manage (quotes, invoices, scopes of work, project plans). Examples: Aceves fence quote, Suttman home services scope. **Deliverable:** structured project record. Final form lives in /manage app; intermediate work product (research, scope drafts, vendor research, materials lists) lives in repo at `customer-jobs/--/`. **Required artifacts during session:** - Project intake structured note: scope, budget if known, deadline, deliverable type. Path: `customer-jobs/--/intake.md`. - Materials/cost research log if scope involves significant procurement. Path: `customer-jobs/--/materials-research.md`. - Handoff block at session end. Same format as equipment kind, path `handoff-blocks/---.md`. **Folder naming convention:** `--/`. Examples: `aceves-home-fence-2026-04/`, `suttman-home-deck-2026-05/`. Property-id is more precise than customer-id since the same customer may have multiple jobs at multiple properties. Multi-property jobs (rare) use `--/` with no property suffix. **Verification priorities specific to this kind:** - Site conditions and measurements verified before quoting. Verbal customer reports of dimensions are starting points, not specs. - Material specifications cited from manufacturer or supplier source. Pricing flagged with date and source — pricing rots faster than specs. - Local code requirements (permits, setbacks, electrical/plumbing standards) cited from municipal source where applicable. Township and county jurisdictions in metro Detroit have non-trivial differences. **Boundary with /manage app:** - This session researches and drafts. The /manage app holds the canonical quote, invoice, and customer record. - Final pricing decisions, payment terms, and customer-facing language: Sam authors in /manage, not here. - Repo holds the supporting research; /manage holds the deliverable. **Out of scope:** - Direct customer communication drafts unless explicitly requested. Default deliverable is internal project record, not customer-facing prose. ### Kind: property **Purpose:** research and documentation about physical properties — Sam's own properties or properties Sam is working on. Examples: Suttman home plan/elevation research, future property scope-outs, parcel data lookups. **Deliverable:** structured property dossier. Path: `properties//dossier.md`. Updated, not versioned (live document with revision history in git). **Required artifacts during session:** - Source citations for every fact in the dossier (parcel records, county GIS, builder plan documentation, MLS history if relevant). - Handoff block at session end if substantive work was done. **Verification priorities specific to this kind:** - Parcel ID, address, and legal description verified from county records (not just user memory or third-party listings). - Floor plan / elevation / square footage verified from builder documentation where available; flag third-party sources (Zillow, Realtor.com) as `// UNVERIFIED` for these specs. - Property history from official records, not aggregator sites. **Out of scope:** - Real estate transaction work (purchase analysis, offer drafting). Different kind of work, different methodology — open as `kind: customer` if it's a service engagement, or as `kind: personal` if it's Sam's own purchase research. ### Kind: personal **Purpose:** Sam's personal research projects unrelated to equipment, customers, or properties. Examples: ACA health insurance research, RC vehicle knowledge base entries, battery technology research, career investigation. **Deliverable:** flexible — depends on project. Common forms: research summary, decision matrix, reference document. Path: `personal//.md`. **Required artifacts during session:** - Source citations applied at the same standard as equipment work. "Personal" does not mean "lower verification rigor" — it means "different deliverable shape." - Handoff block at session end if the project is multi-session. **Verification priorities specific to this kind:** - Match the standard appropriate to the topic. Medical/financial/legal research at the highest standard (primary sources, regulatory documents). Hobbyist research at the standard the topic warrants (RC vehicle specs from manufacturer or established hobby community sources). **Tone differentiation:** - Slightly less formal than equipment work, but not casual. Same technical-peer baseline. Sam still wants to be pushed back on if wrong. **Out of scope:** - Anything that would more naturally be one of the other four kinds. If the topic is equipment-shaped, it's equipment. If it's customer-shaped, it's customer. Use personal for things that don't fit elsewhere. ### Kind: meta **Purpose:** work on the system itself — methodology revisions, workflow design, architectural decisions about how the equipment service archive operates. Examples: this document. The METHODOLOGY.md v1.2 revision. The role-split ADR. **Deliverable:** depends on the work. Methodology revisions land in `METHODOLOGY.md`. Architectural decisions land as ADRs in `architecture/`. Workflow documents land at the repo root. **Required artifacts during session:** - DR for any decision that needs cross-session input. This is the highest-frequency DR-generating kind. - All proposed methodology changes routed through Sam's explicit approval before commit. **Verification priorities specific to this kind:** - Internal consistency with existing methodology and ADRs. Before proposing a new rule, check that no existing rule contradicts it. - Failure-mode analysis on every proposal. New rules should explicitly state what failure mode they prevent and what new failure modes they might introduce. **Boundary with Claude Code:** - This kind generates methodology and architectural reasoning. Claude Code implements the infrastructure consequences (file structure, hooks, CI). - Do not specify implementation details that are Claude Code's call (specific tooling, repo hygiene conventions, deployment mechanics). **Out of scope:** - Implementation work. Sessions of this kind produce design and documentation. Claude Code produces code and infrastructure. --- ## Session end protocol Regardless of kind, session end produces: **1. Handoff block.** Path: `handoff-blocks/-.md`. Standard format: ```markdown --- id: session-date: YYYY-MM-DD kind: --- # Verified configuration [what's confirmed and from what source] # Symptoms / scope [reported state at session start] # Diagnoses / hypotheses considered [with status: confirmed / ruled out / pending] # Actions taken [work done, parts ordered, decisions made] # Outstanding decisions / next steps [explicit list] # Confidence assessment [anything to revisit or verify before next session] ``` **2. Updated entity index.** `index//.md` should be updated with a one-line summary of session outcome and a pointer to the latest handoff block. This is what the next session fetches first to reorient. **3. Kind-specific deliverable.** Equipment: versioned HTML guide if a new version was produced. Customer: project record updates. Property: dossier updates. Personal: research deliverable. Meta: methodology/ADR commits. --- ## Substrate hygiene rules These apply to all sessions: 1. **Never silently degrade.** Per Methodology Principle 4, every fetch failure gets announced. 2. **Never fabricate against missing substrate.** If the template can't be fetched, the session does not render an HTML guide from memory of what the template "probably looks like." It announces and waits for paste-fallback. 3. **Never skip the bootstrap.** Even on a continuation message, if the session realizes its context is stale or uncertain, re-fetch. 4. **Never write outside the kind's path scope.** Equipment session does not write to `customer-jobs/`. Meta session does not write to `guides/`. Path scope is enforced session-side. 5. **Never delegate session-doable work.** Per Methodology Principle 8, check tool inventory before asking the user. Try first, announce if blocked. --- ## Revision history | Version | Date | Changes | |---|---|---| | 1.0 | 2026-04-26 | Initial draft. Five session kinds defined. URL-seeding clause and failure-class differentiation included per LT180/jetski post-substrate-stand-up review. Tool inventory and Principle 8 anchor section included for paired commit with METHODOLOGY.md v1.2. Customer kind path corrected to use the locked `--/` convention. Substrate hygiene rule #5 added pointing at Principle 8. | | 1.0.1 | 2026-04-28 | Added Class 4 (session web_fetch cache serving stale content) to failure class differentiation, with disambiguation against Classes 1 and 2 and the URL-query-string cache-bust mitigation. Surfaced by jetski session blocked on stale METHODOLOGY.md fetch despite verified-current substrate. Patch-level revision; no kind-specific behavior or bootstrap sequence changes. |