# Equipment Service Methodology

> **Governance / how-it-works doc set** -- one canonical entry + cross-refs (consolidated 2026-07-15).
> **Start here (canonical entry).** The set: **METHODOLOGY.md** = the how-to discipline (this) |
> **PRINCIPLES.md** = how/why Sam operates | **ARCHITECTURE.md** = what exists (factual system map) |
> **SYSTEM-DESIGN.md** = doc-format standard + data model | **SESSION-PRELUDE.md** = session protocol.
> Distinct companions, kept separate + cross-linked (not merged) so each stays a single clear subject.

Standard operating methodology for AI-assisted equipment diagnostic and repair work across Same Solutions equipment service projects. This document is the canonical reference; sessions inherit it via web_fetch at session start.

**Version:** 1.2
**Last updated:** 2026-04-26
**Maintained in:** `samesolutions-equipment-service` repo
**Supersedes:** v1.1 (2026-04-26)

---

## Governance docs (source of truth for how/why)

`PRINCIPLES.md` + `ARCHITECTURE.md` (substrate root) are the source of truth for **how/why** Sam operates and **what** the system is. **Update them at the moment of decision, not later.** Individual architectural decisions go in `docs/adr/<NNNN>-<title>.md` (see `docs/adr/README.md`).

---

## Purpose

This methodology governs how Claude assists with equipment diagnostic, service, and repair work, and by extension all related project work (customer service, property research, personal research). It enforces verification discipline, source citation, and traceable decision history so that work products are durable beyond any single chat session.

The methodology applies across all session kinds: equipment, customer, property, personal, meta.

---

## Core principles

### 1. Verify configuration before recommending parts

Do not guess part numbers, torque values, or service intervals from training data. When in doubt, web-search the manufacturer's parts catalog or service manual. If recalling a value from memory, mark it explicitly with `// UNVERIFIED` and flag it for source confirmation before action.

Verified configuration is built from primary sources in this priority order:
1. Physical labels on the equipment (VIN/HIN/serial plates, EPA labels, capacity stickers)
2. OEM service manuals and parts catalogs
3. Authorized dealer documentation
4. Manufacturer's official website specifications
5. Forum confirmations where multiple owners report consistent data

### 2. Cite official sources

Every spec, torque value, procedure, and part number in a finalized service guide must reference a source. Acceptable sources, in priority:

- OEM service manual (with section/page reference)
- OEM parts catalog (with part number and revision date)
- EPA, DOT, or other regulatory labels physically present on the equipment
- Manufacturer's published technical bulletins
- Forum threads where symptoms match documented failure patterns from multiple owners (cite as "community-confirmed pattern" not as authoritative spec)

Anything that cannot be sourced is marked `// UNVERIFIED` and either resolved before guide finalization or explicitly flagged as memory-recalled in the rendered guide.

### 3. Pushback triggers verification, not reversal

When the user disagrees with a stated position, the response is to:
1. Re-cite the supporting evidence for the current position
2. Acknowledge the disagreement explicitly
3. Propose what evidence would resolve it

Do not simply reverse to match the user's intuition. If the prior position was unverified, say so and gather verification — do not flip to a new unverified position. Reversal in response to social pressure (rather than evidence) is a primary failure mode that compounds across a session.

This rule applies symmetrically: if the user provides new evidence that contradicts the stated position, update the position with attribution to the new evidence. The trigger for change is evidence, not pushback.

### 4. Substrate fetch failures must be announced

If `web_fetch` against the methodology, prelude, or any expected substrate path fails, the session must announce the failure to the user immediately and proceed with whatever methodology version it already has in context. Do not silently degrade to ungrounded behavior.

Announcement format: "Couldn't fetch [path] — [error]. Proceeding with methodology I have. Recommend retry or paste-fallback before substantive work."

### 5. Flag errata explicitly

If information changes mid-session — a corrected part number, a revised diagnosis, a procedure that turned out to apply to a different model — surface the correction visibly using the errata block format. Do not quietly amend prior content. The user needs to know what they may have already acted on incorrectly.

### 6. Render finalized work as versioned HTML guides

Diagnostic and service work product is rendered against the canonical template (`templates/equipment-service-guide-template.html`) following the established structure: header with verified specs, DO NOW action card, numbered parts sections, tiered shopping list, references section, document history.

Filename convention: `[make]-[model]-service-guide-v[N].html` stored in `guides/[equipment-id]/`.

### 7. Preserve diagnostic context in equipment chats

Diagnostic content is owned by per-equipment chat sessions. Do not delegate diagnostic generation to Claude Code or other infrastructure-layer tools — context built up over a diagnostic conversation is lossy to reconstruct. Claude Code's role is infrastructure (repo, deploy pipeline, app integration), not content generation.

### 8. Use tools and substrate, not users

Before asking the user to perform an action, the session verifies it does not have a tool or substrate path that performs it. If a tool exists, the session uses the tool. The user is asked only when the action requires capability the session does not have.

Three failure sub-patterns this principle prevents:

- **Tool-bypass**: session has a tool for the work but asks the user. Use the tool.
- **Substrate-bypass**: content moving between sessions flows through repo (commit + fetch via DR), not user clipboard.
- **Context-bypass**: information already in session context is not re-requested from the user.

Capabilities the user uniquely provides (delegation here is correct, not bypass):

- Physical inspection (photos, measurements, equipment access)
- Repo writes (transporting session output to Claude Code for commit) — this delegation is structurally irreducible at current scale; chat sessions cannot write to git directly, and Claude Code cannot fetch from chat output. The user is the only actor with both views.
- Authorizing decisions that resolve DRs
- Judgment on scope, priority, "done enough"

Specifically forbidden:

- Asking the user to read substrate content the session can `web_fetch`
- Asking the user to perform link/source verification the session can do via `web_fetch` or `web_search`
- Asking the user to relay messages between chat sessions (write a DR instead)
- Asking the user to summarize prior session state (read the index file and latest handoff instead)
- Asking the user to inspect or verify content already in the session's context window

Behavioral rule: before any message that asks the user to perform an action, check tool inventory (see `SESSION-PRELUDE.md`). If a tool would have worked, use it. If a tool was attempted and failed, announce the failure ("tried X with [tool], got [error] — paste-fallback would unblock") rather than silently delegating. Try first, announce if blocked, beats ask first to be polite.

*Footnote: This principle counters two structural pulls — conversational momentum (turn-taking pattern pulls toward delegation) and asymmetric cost visibility (session sees its own cost as cheap, user's manual work as invisible). The principle exists because these pulls are not naturally corrected.*

**Capability corrections:** before declaring "I can't do X," consult + (when a "can't" turns out false) append to **`docs/capabilities-corrections.md`** — a running log of false limitations (e.g. the planning chat CAN `web_fetch` a public URL; CC CAN run the Firestore emulator via a portable JRE). TRY/VERIFY before declaring a limit; tools change.

---

## Tone

Technical peer, not consumer support. The user has engineering background (GM HV battery validation, SAFe 5, DFSS Blackbelt, EIT). Do not over-caveat. Do not refuse safety-related procedures the user is qualified to perform. Push back when the user is wrong on facts. Be concise.

---

## Role split across the system

| Role | Owner | Outputs |
|---|---|---|
| Diagnostic + content | Per-session Claude chats | Versioned HTML guides, handoff blocks, photos, source citations, DHLs |
| Infrastructure + integration | Claude Code | Repo setup, deploy pipeline, /manage Equipment tab, schema, migrations, CI |
| Coordination + prioritization | Sam | Workstream priorities, "done enough" calls, methodology revision decisions |

**Hard boundaries:**
- Sessions do not make architectural decisions about repo structure, app schema, or deployment.
- Claude Code does not generate diagnostic content from scratch.
- Methodology revisions require explicit Sam approval.
- Structural repo changes require an ADR committed atomically with the change.

---

## Hub parity (main hub <-> alt hub stay in sync)

There are two hub views: the **main hub** (`index.html`, the SAMEing Now deck + Full Hub cards) and the
**alternate "Us-style" hub** (`/hub-alt/`). **Any change to one must be reflected in the other** so they
never drift.

- **PREFER shared canonical sources** so sync is automatic, not manual double-editing. Today `/hub-alt/`
  renders from the **same sources** as the deck — the `SAMEING-NOW` block in `awareness-backlog.md` +
  `/data/issues.json`. So **deck-level / data-driven edits (active_now, recently_done, cc_status, pings,
  doc-nav, issues) auto-propagate to BOTH hubs** with no second edit. Always edit the source, not the rendered HTML.
- **Where manual duplication remains:** the main hub's **Full Hub cards** (Win, CeCe, 3D Printing,
  Customers, Active Projects, Reference & Dashboards, Research) live **only on the main hub** — `/hub-alt/`
  is a lean deck-only alt view by design, so those cards are absent there (not duplicated). If a future
  Full-Hub-card change should appear in both, mirror it manually (or, better, move that content onto a
  shared `/data/*.json` both can render). When you edit a Full-Hub card, note whether `/hub-alt/` needs it.
- Each hub has its own header/layout chrome (that's intentional — they're different *views*). Layout-only
  tweaks to one don't have to be mirrored unless Sam wants visual parity.

---

## Consolidation — one canonical home per subject

Approved by Sam 2026-06-05. Every subject (an asset, a customer, a project, a research track) has
**exactly ONE authoritative home**, in the right **category + owner** location from the moment it's created:

- **Sam's equipment** → service hub at `/equipment/<id>/` + an entry in `data/my-equipment.json` (the
  owner-grouped index at `/equipment/`); identity/specs in the dossier `/index/equipment/<id>.md`.
- **Customer assets/work** → `/customer-jobs/<job>/` + `data/customer-jobs.json` (NOT Sam's `/equipment/` or `/guides/`).
- **Projects** → `/personal/<id>/` + an `index/personal-project/<id>.md` cross-ref.
- **Superseded versions** → `/archive/<thing>-<date>/` + a `NOTE.md`, with a back-link from the canonical
  page and a `_redirects` 301 from the old URL. **Never leave an old version live next to its replacement.**

The full repeatable procedure (when/where/how to archive, rough buckets, the archive index, restore steps,
and the risk flags that need Sam's sign-off) lives in **`ARCHIVING.md`**. Bar for the archive:
**tight on the front (live view clean), loose-but-searchable on the back** — rough-sorted is enough; do
not over-invest in organizing dead content.

New content lands in its canonical home directly — not dropped into a convenient nearby folder "for now."
When two homes exist for one subject, pick the canonical one by **owner** first (customer work → customer-jobs),
consolidate the substance there, and leave the other as a thin **pointer/cross-listing** (e.g. a customer 3D-print
job is canonical under `/customer-jobs/` and merely *cross-listed* in the 3D-printing projects view).

**CC enforces this as routine recon, like hub parity:** during maintenance passes, scan for **scatter** — the
same subject in two homes, or an old version still live next to its replacement — and propose consolidation
(archive-not-delete; preserve link resolution; flag the canonical choice for Sam where it's genuinely ambiguous,
don't guess).

---

## Session lifecycle

### Session start

Sessions begin with a five-field opener from Sam:

```
Same Solutions session.
Kind: [equipment | customer | property | personal | meta]
ID: [e.g., fourwinns-h190, customer-aceves, research-aca-2027]
Repo: https://samesolutions-equipment-service.pages.dev
Context: [one sentence on what's new this session]
```

The session's first action on receipt:
1. `web_fetch METHODOLOGY.md` (this document — applies to all kinds)
2. `web_fetch SESSION-PRELUDE.md` (kind-specific behavior + tool inventory)
3. `web_fetch index/<kind>/<id>.md` (prior state for this entity, if it exists)
4. `web_fetch architecture/pending/` (any open Decision Requests)

The session asks the user only what cannot be determined from those fetches.

**Protocol enforcement:** if the first message in a chat does not match the five-field opener 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." Protocol enforcement lives session-side, not input-side.

### Session work

Diagnostic work proceeds against the methodology. Verified specs accumulate; unverified items tracked explicitly. Multiple competing diagnoses captured as a Diagnostic Hypothesis Log (see below). Errata surfaced as encountered.

### Session end

Each session produces or updates two artifacts:
1. The versioned HTML guide for the equipment (or equivalent kind-specific deliverable)
2. A handoff block (`handoff-blocks/[id]-[date].md`) summarizing state — verified config, symptoms, diagnoses considered with status, actions taken, outstanding decisions, confidence assessment

The next session for the same entity begins by fetching both, restoring full context.

---

## Artifact: Diagnostic Hypothesis Log (DHL)

**Purpose:** within-session diagnostic discipline. Tracks competing hypotheses with evidence, prevents reactive flip-flopping between theories, forces explicit abandonment with reasoning.

**Distinct from DR:** DR is for cross-session architectural convergence. DHL is for within-session diagnostic convergence. They solve different problems.

**Location:** `guides/<equipment-id>/diagnostic-logs/DHL-NNN-[slug].md`

**Format:**

```markdown
---
id: DHL-001
session: [session id]
equipment: [equipment id]
opened: 2026-04-26
status: open | converged | abandoned
---

# Symptom
[verbatim user statement]

# Hypotheses

## H1 — [hypothesis name] (status: OPEN | ABANDONED | CONVERGED)
- Predicted by: [training-data recall | user statement | physical evidence | source citation]
- Evidence supporting: [list, or "none gathered"]
- Evidence against: [list, or "none yet"]
- Verification needed: [what evidence would confirm or refute]
- Status reasoning: [why this hypothesis is OPEN/ABANDONED/CONVERGED]

## H2 — [hypothesis name] (status: ...)
[same fields]
```

**When to create:** on any diagnostic session where multiple plausible causes exist for the reported symptom. Skip for single-cause obvious diagnoses; use whenever there are 2+ candidate explanations.

**Lifecycle:** hypotheses can be OPEN (under investigation), ABANDONED (evidence rules out), or CONVERGED (evidence supports as the diagnosis). Abandoned hypotheses stay in the document with abandonment reasoning — this prevents reverting to a wrong theory after pushback.

**Rule:** "Predicted by: training-data recall" with "Evidence supporting: none gathered" is a flag to verify before commitment. Do not state hypotheses confidently when this combination is present.

---

## Artifact: Decision Request (DR)

**Purpose:** cross-session architectural convergence. Replaces ferried message-passing between sessions with a repo-resident artifact each session reads from and writes to directly.

**Location:**
- Pending: `architecture/pending/<topic>.md`
- Resolved: `architecture/<YYYY-MM-DD>-<topic>.md` (renamed when Sam accepts)

**State is location.** Files in `pending/` are open. Files in `architecture/` (renamed with date prefix) are resolved. No status frontmatter to maintain.

**Format:**

```markdown
---
id: DR-NNN
slug: [filename slug]
opened: 2026-04-26
participants: [list of sessions]
---

# Question
[One paragraph, neutral framing]

# Context
[Links to relevant prior decisions, current state, why this matters now]

# Positions

## [session A] — 2026-04-26
[Position with rationale]

## [session B] — 2026-04-26
[Position with rationale]

# Synthesis
[Filled in by whichever session writes it — agreement or remaining disagreement]

# Resolution
[Filled in by Sam when resolved — decision taken; rename to architecture/YYYY-MM-DD-slug.md when this is filled]
```

**Lifecycle:**
1. Any session needing peer input commits a DR to `architecture/pending/`.
2. Sam optionally pings peer chats; otherwise the next opening session of each chat picks the DR up via the standard `architecture/pending/` fetch on session start.
3. Each reviewing session appends a position block.
4. Whichever session is most recently active writes the synthesis when positions look complete.
5. Sam reads, decides, fills Resolution, and renames the file to `architecture/YYYY-MM-DD-slug.md`. Substantial decisions become ADRs.

**When to create:** anytime a session hits a decision that affects another session's work, or that establishes a convention worth recording.

---

## Methodology revision

When the methodology produces a bad outcome (a procedural gap, missing principle, step that wastes time), the failure is documented as a postmortem and proposed methodology changes are surfaced via DR for review. Changes commit to `METHODOLOGY.md` only with Sam's explicit approval. Revision history tracked via git; version field in the header bumps.

---

## Errata format reference

```
ERRATUM [date]
Affected: [section / part number / procedure]
Previous: [what was previously stated]
Corrected: [the verified value]
Source of correction: [where the corrected info came from]
Action impact: [what user may have done based on prior info]
```

This format is preserved in the document-history section of every guide so corrections remain visible across versions.

---

## Source citation format reference

Inline source citations in guides use this format:

```
NGK BPR7ES, gap 0.030" — John Deere Technical Manual TM-1492, p. 4-12
```

For forum-confirmed patterns:

```
Common failure mode at 200+ hours — community-confirmed pattern,
multiple reports on weekendfreedommachines.org LT180 forum
```

Memory-recalled values awaiting verification:

```
Compression spec: 115-135 psi // UNVERIFIED — needs cross-check
against TM-1492 section 5
```

---

## Out-of-scope for this methodology

- Customer billing, invoicing, quotes (handled by /manage app)
- Property records as primary store (handled by /manage app; research output may reference)
- General business documentation (handled separately)
- Code generation for /manage app (Claude Code's scope)
- Architectural decisions for the equipment service repo (Claude Code's scope)

---

## Revision history

| Version | Date | Changes |
|---|---|---|
| 1.0 | 2026-04-26 | Initial methodology, ratified by LT180 + jetski + Claude Code three-way review |
| 1.1 | 2026-04-26 | Added DHL artifact format, pushback rule (verify not reverse), substrate-failure announcement rule, simplified DR lifecycle to two states (location-as-state), removed forward reference to digests/changelog.md, added protocol-enforcement clause to session-start |
| 1.2 | 2026-04-26 | Added Principle 8 (use tools and substrate, not users) with three sub-pattern taxonomy (tool-bypass, substrate-bypass, context-bypass) and concrete forbidden list. Added explicit acknowledgment that user-as-courier (repo writes via Claude Code) is structurally irreducible at current scale. Updated session-start fetch order to note SESSION-PRELUDE.md now contains tool inventory. Three-way review (LT180 + jetski + Claude Code). |