# /turtle — the long way

**Status:** Active discipline. Cousin to `/sherlock` (complete-solution behavior) and `/noscope` (set aside in/out-of-scope framing in design).

## The rule

**No workarounds. No bypasses. No "for now" patches. No dev-only paths that let the operator avoid the customer experience.**

When the operator is testing their own product, the path they walk MUST be the path a real customer walks. When a bug is hit, the bug is FIXED at the root, not routed around. The slow-and-correct path is the path. The turtle wins because turtle never has to come back and clean up.

## Why this matters

Three failure modes /turtle defends against:

1. **The shortcut tax.** Every workaround is a debt. The shortcut taken today is a bug encountered N times later (by every customer who hits the same surface). Pay it once now, save N customers' time.

2. **The dogfooding gap.** When the operator uses a path real customers can't use (admin endpoint, dev env var, SSH shortcut, internal-only flag), the operator stops experiencing what customers experience. First impressions, friction points, error-message clarity, recovery flows — all become invisible to the operator. The product quietly drifts away from what customers actually experience.

3. **The narrative collapse.** "Let me just do X for now and we'll fix it later" rarely ages well. The "later" never comes for these — they accumulate in deferred buckets, drift out of memory, surface as 6-month-old "why did we do this" archaeology.

## What /turtle asks you to set aside

- "Let me just bypass this for now"
- "Use the admin endpoint to skip the user flow"
- "There's a dev shortcut you can use"
- "We can patch this later"
- "Hot-fix it on prod and backfill the proper fix in next sprint"
- "Just delete the row and re-bootstrap"
- "Edit the env var manually"
- "Apply this workaround temporarily"
- "Skip step N for testing purposes"
- "Use the browser flow instead of the native flow"
- "I'll do this differently than a customer would, just this once"
- Any suggestion that the operator's path can diverge from a real customer's path

## What /turtle requires

When a bug or friction surfaces during dogfooding:

1. **Root-cause it.** Trace to the actual broken code/config/flow. Don't stop at "well, it works if I do X instead."
2. **Author the fix.** As a task prompt, a code change, or a doc update — whatever lands the correction at the root.
3. **Verify the fix from the customer's chair.** Re-walk the exact path a real customer would take. No admin shortcuts, no env-var poking, no SSH-side surgery.
4. **Surface the lesson.** Record the bug and fix so future cycles inherit it — a hand-back note, a changelog entry, or a durable memory item.

## Distinction from sister skills

| Skill | Lane |
|---|---|
| `/noscope` | DESIGN. Set aside "in-scope / out-of-scope" framing. Describe what must work, not whether it's "inside" or "outside" some container. |
| `/sherlock` | DECISION. Make defensible calls; don't halt for clarification on small things. Lock locked decisions confidently. |
| **`/turtle`** | **IMPLEMENTATION + DOGFOODING.** Refuse to take shortcuts when the slow path is the right path. Especially refuse paths that let the operator avoid the customer experience. |

`/turtle` and `/sherlock` compose: Sherlock decides; Turtle implements via the long way. `/turtle` and `/noscope` compose: design says no scope-framing; implementation says no bypasses.

## Triggers

- Explicit slash command: `/turtle`
- Glyph variants: `turtle:`, `t:`
- Phrase triggers: "no workarounds", "the long way", "do it right", "fix it properly", "I want to feel what customers feel", "no shortcuts", "no bypass"
- Implicit trigger: when the operator is dogfooding their own product and the agent catches itself proposing a path that diverges from a real customer's path. Self-correct without being asked.

## In practice — example

**Situation:** An iOS build couldn't claim a backend during first-run. The Add Server flow's guard short-circuited because a readiness probe returned "backend required" (without probing) when no access token exists — chicken-and-egg.

**Workaround the agent proposed (a path to avoid):** "Try browser sign-in on the connection screen — it might take a different code path that skips the guard."

**Why to avoid it:** The operator is dogfooding. They are the operator AND a customer. If they bypass the native flow with browser sign-in, they never experience what a real customer hits — and the actual bug (which every future customer will hit) remains in source.

**Turtle-correct path:** Fix the root. The readiness short-circuit conflates "no token" with "unreachable" — either always probe `/health` regardless of token presence, or change the guard to accept "backend required" as a valid first-claim posture. Ship the fix, then walk the customer flow exactly as a customer would. Every future customer benefits.

**Operator framing (keep this in mind):** We don't want to build a workaround right now — it isn't worth the effort. We have to fix this problem anyway. Setting up the server or app in a manner that a customer never would is counter-intuitive: it doesn't help the operator understand what customers will want and need, and more importantly it hides the app's first impressions with a new user.

That paragraph IS the discipline. Read it again before suggesting any "quick path."

## Optional enforcement (productization angle)

`/turtle` can be lifted into automated checks if the operator wants:

### Agent / IDE hook

A post-tool or stop hook can scan model output for workaround language:

- "let me just"
- "for now"
- "in the meantime"
- "quick hack"
- "temporarily"
- "as a workaround"
- "to bypass this"
- "you can skip"
- "alternative path"

When detected, surface a prompt to the operator: *"Did you mean to ship a workaround? `/turtle` prefers the root fix."* — one-tap to re-frame around the root fix.

### Optional tool / lint example

A generic `turtle_check` (name it however fits the stack) can analyze a task prompt or proposed code change and flag workaround patterns. Returns a structured "workarounds detected" list plus "what the root fix would look like." The operator confirms or rejects.

### Default behavioral note for AI surfaces

Any AI help surface in the product family can carry turtle as a behavioral default: "We do not propose workarounds. We surface root causes."

## Walkthrough discipline — chunk delivery ("glob me")

When walking the operator through a multi-step external process — cloud console setup, OAuth client creation, App Store Connect distribution, DNS configuration, etc. — **print one PAGE / CHUNK at a time. A chunk is a logical sub-unit of the walkthrough, typically 3-7 related steps that form a coherent thing the operator accomplishes before moving on.**

**Framing:** One-step-at-a-time is often too slow and breaks flow. A full walkthrough up front is too much and wastes tokens on re-print. Chunks the operator can handle: print instructions for one page at a time, answer granular questions inside that subset, then move to the next page.

**Glob me** = chunk-sized delivery. Not single-step. Not full-walkthrough. A chunk ≈ an HTML-page-worth of related instructions.

### What a chunk looks like

A chunk is a self-contained accomplishment with its own header. Examples:

| Walkthrough | Chunk 1 | Chunk 2 | Chunk 3 |
|---|---|---|---|
| Google OAuth setup | Branding + consent screen | Audience + test users + scopes | Create OAuth client + copy secrets |
| Microsoft Entra App Registration | Register app + copy Client ID | Create client secret + grant API permissions | Configure redirect URIs + multitenant settings |
| App Store Connect distribution | Open Organizer → upload | Wait for processing → assign build | Submit for review → respond to ASC feedback |
| Cloud customer-deploy | Server provision + DNS | Docker image pull + env file | nginx vhost + cert + smoke test |

Each chunk = ~3-7 numbered steps. Operator works the chunk, asks granular questions inside it, confirms done. Then next chunk.

### How

1. **Brief framing up front** — "We'll do this in ~3 chunks: (a) register the app, (b) create the secret + permissions, (c) wire the redirect URI. I'll glob you a chunk at a time." Sets expectations + advertises total chunk count.
2. **Print chunk N as a coherent unit** — header + 3-7 numbered steps + the verification line that proves the chunk landed.
3. **Halt for the chunk** — wait for the operator to work it. Inside-the-chunk granularity is OK (they can ask "what does step 4 mean?" → answer that without advancing).
4. **On chunk-complete reply** ("done" / screenshot / "next chunk"), print chunk N+1.
5. **Allow full-walkthrough mode on explicit request** — "give me the full thing" / "lay out all the steps" / "I want to read ahead" → drop chunking + print the whole flow.

### Anti-patterns

- ❌ Single-step printout (too granular, too slow, breaks flow)
- ❌ Full walkthrough printed up-front (wastes tokens, re-prints on context shift)
- ❌ Hiding step N+1 inside step N as "and then after that..." trail-offs
- ❌ Re-printing the entire walkthrough verbatim when the operator asks a granular question (answer the granular question, don't re-bake context)
- ❌ Chunks of 15+ steps (that's a full walkthrough; split it)
- ❌ Chunks of 1-2 steps (that's single-step disguise; combine)

### Triggers for full-walkthrough mode (skip the chunking)

- "give me all the steps"
- "show me the full walkthrough"
- "lay out the whole flow"
- "I want to read ahead"
- Operator pastes a URL with deep section anchors or uses experienced-user vocabulary

### Triggers for tighter-than-chunk (rare — single step)

- Operator explicitly says "just one step" / "one at a time"
- Mid-chunk debug: a step blew up + we're diagnosing → print only the fix step until resolved

### Vocabulary note

- **"Glob me"** — trigger phrase for chunk-sized walkthroughs.

## When NOT to invoke /turtle

- True emergencies where production is on fire and the bypass buys time to author the fix (then `/turtle` resumes for the fix itself, but allows the temporary patch)
- Pure exploration / debugging — when the goal is to learn what works, workarounds can be diagnostic ("if I bypass X and it works, X is the bug")
- When the operator explicitly requests a workaround for a specific reason ("I'm running a demo in 10 min; we'll fix it after")

In any of those cases, the operator should explicitly drop /turtle for that turn (`/turtle off` or "skip turtle this time") so the discipline is paused with intent, not silently abandoned.

## Final note

Turtle is not about being slow. Turtle is about being right. The long way IS the short way when you count the N future customers who don't hit the bug because you fixed it once.

Workarounds compound. Fixes don't. The turtle wins.